fs

Samuel Boyden's Portfolio

This is the repository containing the source code for my portfolio hosted at https://stboyden.com.

The code is written primarily using Golang as the language for the back-end server, and using Templ to generate server-side pages, using HTMX and AlpineJS to improve client-side interactivity and to emulate a SPA feel. I also use TailwindCSS and DaisyUI to style the site, to make it look simple yet consistent.

Additionally, I am implementing a custom blog system for this site, backed by PostgresQL for storing posts.

Tools used

I leverage a few tools to make this application work, most are Go-specific and are specified in the go.mod file using the go get -tool command introduced in Go version 1.24. As such, as long as you have the appropriate Go toolchain installed, they will be fetched alongside the dependencies when go mod download is ran.

The tools used are:

• cmd/templ from a-h/templ to generate Go code from the .templ files in internal/pkg/routes/site/views.
• air from air-verse/air to run a local development with semi-hot reloading (or lukewarm hot-reloading). air watches for source code changes in relevant directories and then automatically rebuilds the site (I mention that it's semi-hot reloading because I have not setup air to refresh the site in the browser, so manual refreshing is required).
• cmd/sqlc from sqlc-dev/sqlc to generate appropriate DB-related code from the schema in migrations and queries in queries.

Running locally

If you would like to run a local copy, I recommend two commands that will make your life easier. Both are technically optional, but I will strongly recommend them nonetheless.

1. just from casey/just - Just is a task executor, similar to make, but is more cross-platform which makes it more accessible for development on Windows. I personally develop on Linux, but the tasks should run fine on Windows. If you don't want to install this tool, that's fine, you'll just have to make sure you follow the commands in the justfile for the relevant commands to run for the task you want to do.
2. docker from https://www.docker.com - Docker is used to host a local development PostgresQL database for the blog system. If you already have a local PostgresQL instance that you want to use instead, make sure that you correctly set the DB_URL environment variable to compensate.

Steps

1. (Optional) Create the PostgresQL instance from the docker-compose.yml file:

   docker compose up -d
   

2. Create a .env file with the following content:

   # your GitHub PAT
   GITHUB_TOKEN=ghp_xxxxxxx
   
   # the connection string to the database instance, see docker-compose.yml for the default connection string
   DB_URL=xxxxxxx
   
   # the admin username
   ADMIN_USER=xxxxxxx
   
   # md5 hash of the admin password
   ADMIN_PW=xxxxxxx
   

3. Run migrations on the database instance to get it to the correct state and generate types based on the updated schema:

   # this will run migrations first *then* generate the correct types
   just generate_db_types
   

4. Build & run the project:

   just build
   just run
   

[!NOTE]

Assuming no errors have been output, then the local instance will be available at http://localhost:8080.

1. (Optional) If you want to have the site live-update with changes:

   just dev
   

[!NOTE]

As above, your instance will be hosted at http://localhost:8080, but after any changes you will have to manually refresh the page (with F5) as I have not set up the project to work properly with hot-reloading.

Deployment

For deployment, I use fly.io to deploy a Docker container. It should be relatively simple to deploy the Docker container anywhere that supports that functionality, however I chose fly.io for simplicity. The container specification can be found in Dockerfile.

Project structure

Last updated: commit 0e4e17a

The structure of the project is similar to that of most standard Golang applications, with some changes to accomodate the needs of the project.

[!NOTE] Most of the "interesting" stuff will be in the subdirectories of internal/pkg, which contains most of the business logic of the site.

/
|-- /cmd
|   |-- /main             # contains application code for the main site
|   |-- /migrations       # contains application code for running migrations
|
|-- /internal
|   |-- /pkg
|   |   |-- /common       # contains utilities and common types
|   |   |-- /middleware   # middlware for the api
|   |   |-- /persistence  # generated by sqlc per the db schema
|   |   |-- /routes       # api route handlers
|
|-- /migrations           # contains handwritten sql migration files in the
|                         # format golang-migrate expects
|-- /queries              # contains sql files used by sqlc to generate Go
|                         # code