4225d0a3a4 | ||
---|---|---|
adminmailer | ||
cinera | ||
fishbowl-tools | ||
local | ||
public | ||
server | ||
src | ||
.gitignore | ||
README.md | ||
go.mod | ||
go.sum | ||
main.go |
README.md
Handmade Network
This is the codebase for the Handmade Network website, located online at https://handmade.network. The website is the home for all Handmade projects, the forums, the podcast, and other various initiatives.
The site is written in Go, and uses the standard library HTTP server with custom utilities for routing and middleware. It uses Postgres for its database, making heavy use of the excellent pgx library along with some custom wrappers. See the documentation in the db
package for more details.
We want the website to be a great example of Handmade software on the web. We encourage you to read through the source, run it yourself, and learn from how we work. If you have questions about the code, or you're interested in contributing directly, reach out to us in #network-meta on the Handmade Network Discord!
Prerequisites
You will need the following software installed:
-
Go 1.18 or 1.19: https://go.dev/
You can download Go directly from the website, or install it through major package managers. If you already have Go installed, but are unsure of the version, you can check by running
go version
.PLEASE NOTE: Go 1.20 currently does not work due to a bug in a third-party library. See this issue.
-
Postgres: https://www.postgresql.org/
Any Postgres installation should work fine, although less common distributions may not work as nicely with our scripts out of the box. On Mac, Postgres.app is recommended.
First-time setup
-
Configure the site. Copy
src/config/config.go.example
tosrc/config/config.go
:# On Windows copy src\config\config.go.example src\config\config.go # On Mac and Linux cp src/config/config.go.example src/config/config.go
Depending on your installation of Postgres, you may need to modify the hostname and port in the Postgres section of the config.
-
Set up the database. Run
go run . db seed
to initialize the database and fill it with sample data. -
Update your hosts file. The website uses subdomains for official projects, so the site cannot simply be run off
localhost
. Add the following line to your hosts file:127.0.0.1 handmade.local hero.handmade.local 4coder.handmade.local
You may need to edit the hosts file again in the future if you add more official projects.
On Windows, the hosts file is located at
C:\Windows\System32\Drivers\etc\hosts
. On Mac and Linux, the hosts file should be located at/etc/hosts
. It can be edited using any plain text editor, but you will need superuser permissions.
Running the site
Running the site is easy:
go run .
You should now be able to visit http://handmade.local:9001 to see the website!
There are also several other commands built into the website executable. You can see documentation for each of them by running go run . help
or adding the -h
flag to any command.
Running tests
Also easy:
go test ./...
Note that we have a special coverage requirement for the hmnurl
package. We use the tests in this package to ensure that our URL builder functions never go out of sync with the regexes used for routing. As a result, we mandate 100% coverage for all Build
functions in hmnurl
.
Starter data
The db seed
command pre-populates the site with realistic data. It also includes several user accounts that you may log into to test various situations:
Username | Password |
---|---|
admin |
password |
alice |
password |
bob |
password |
charlie |
password |
The admin
user is a superuser on the site and will have access to all features, as well as the special admin UI for performing site maintenance and moderation. The other users are all normal users.