Minimal Kamal

A minimal Go application demonstrating a complete modern deployment stack using Kamal 2, Litestream, and SQLite.

Read the accompanying blog post: Deploying Go with Kamal

Features

• Go 1.26 Backend: Simple and efficient TODO application.
• CGO-free SQLite: Uses modernc.org/sqlite for easy cross-compilation.
• Kamal 2 Deployment: Zero-downtime deployments with Traefik and automatic SSL.
• Litestream Backup: Continuous replication of the SQLite database to GCS.
• Distroless Docker Image: Minimal and secure production environment.

Tech Stack

• Language: Go
• Database: SQLite
• Deployment: Kamal 2
• Backup: Litestream
• Proxy/SSL: Traefik (via Kamal)

Getting Started

Prerequisites

• Go 1.26+
• Docker
• Kamal 2

Local Development

1. Clone the repository:

   git clone https://github.com/your-username/minimal-kamal.git
   cd minimal-kamal

2. Prepare the data directory: The application expects the database to be in the ./data directory.

   mkdir -p data

3. Run the application:

   go run main.go

   The server will start at http://localhost:8080.

Deployment

1. Configuration

Review and update the following files:

• config/deploy.yml: Update the service, image, servers, and proxy.hosts.
• config/litestream.yml: Update the replica URL (e.g., your GCS bucket).
• .kamal/secrets: Add your SMTP_PASS and LITESTREAM_APPLICATION_SECRET.

On the server, make sure the data folder is writeable by the user that runs inside the container. In this case, the distroless nonroot image runs everything as user 65532 and group 65532, which means you'll have to make it writeable for that user (or just change the owner of the folder to that user as shown below). The user does not need to exist on the host system, only the UID and GID need to match.

chown -R 65532:65532 data

2. Setup & Deploy

Initialize the server and deploy the application:

# Setup the server (first time only)
kamal setup

# Subsequent deploys
kamal deploy

3. Monitoring

• Check logs: kamal app logs -f
• Check status: kamal details

Project Structure

├── config/
│   ├── deploy.yml         # Kamal deployment configuration
│   └── litestream.yml     # Litestream backup configuration
├── db/
│   └── db.go              # Database logic (SQLite)
├── handlers/
│   └── handlers.go        # HTTP handlers
├── models/
│   └── todo.go            # Data models
├── templates/
│   └── index.html         # Frontend templates
├── main.go                # Application entry point
├── Dockerfile             # Production build configuration
└── go.mod                 # Go dependencies

License

MIT