Alloy is a starter template for creating web applications using Go programming language. It does not aim to be a web framework but is instead a collection of useful libraries and packages that acts a sensible starting point.

Recently, I decided to build my latest side project using Go. I started off with just the standard library and then gradually added a few recommended packages for performing common tasks like database calls (sqlx), migrations (pressly/goose) and sending emails (gomail). This boilerplate has been extracted from that side project.

Alloy uses Webpack for managing front-end assets (Javascript and CSS), so you need to have Node.js and NPM installed in order to use that. This boilerplate also includes a separate 'admin panel' which acts as a CMS for adding pages, managing users etc.

Packages used

  • go-chi/chi
  • lib/pq
  • jmoiron/sqlx
  • markbates/pop/nulls
  • gorilla/sessions
  • gorilla/csrf
  • gorilla/securecookies
  • markbates/refresh
  • microcosm-cc/bluemonday
  • pkg/errors
  • pressly/douceur
  • pressly/goose
  • satori/go.uuid
  • spf13/cobra

Available commands

  alloy [command]

Available Commands:
  db          Manage the app's database (create migration, migrate up/down/redo).
  dev         Start the development server (along with webpack watch)
  gen-key     Generate a random key to use with securecookies
  help        Help about any command
  new-admin   Manage the admin user(s)
  server      Start the server
  version     Print the version number of alloy

Installation and usage

  1. Clone the repository
git clone
cd alloy
  1. Install the dependencies
glide install
npm install
  1. Create the following environment variables.
ENVIRONMENT=development (change to 'production' in the production environment)
CSRF_KEY=XXX (replace with 32 character string (use the gen-key command))
HASH_KEY=XXX (replace with 64 character string (use the gen-key command))
BLOCK_KEY=XXX (replace with 32 character string (use the gen-key command))
MAILER_FROM=XXX (e.g: [email protected])
ASSET_URL=http://localhost:1212 (if you are using a CDN in production, this can be set to that URL)
  1. Start the development server
go install
alloy dev

Now you can open your browser and navigate to http://localhost:1212 to see it in action. Any changes you make to the .go files will be automatically picked up and the app will be re-compiled.

Project structure

    ├── app
    │   ├── handlers
    │   ├── mailer
    │   ├── migrations
    │   ├── models
    │   ├── router
    │   │   ├── middleware
    │   │   └── router.go
    │   ├── services
    │   │   ├── db.go
    │   │   └── session.go
    │   ├── templates
    │   │   ├── admin
    │   │   ├── layouts
    │   │   ├── mailer
    │   │   ├── pages
    │   └── views
    ├── assets
    │   ├── fonts
    │   ├── images
    │   ├── js
    │   └── scss
    │       ├── admin
    │       ├── frontend
    │       └── frontend.scss
    ├── cmd
    ├── testutils
    ├── glide.yaml
    ├── main.go
    ├── package.json
    ├── refresh.yml
    └── webpack.config.js






If you have any questions or comments, please get in touch via email or open an issue. I would welcome your suggestions and pull requests.