Broilerplate

A template project for new Go web backend applications.

Can be used as a starting point for quickly prototyping a REST API or fully-fledged server-rendered web application in Go, backend by a relational database and common authentication / authorization. Originating from my work on wakapi.

🚀 Features

• Data management
  • Easy-to-use ORM to map between Go struct and databases entities
  • Multiple databases supported, including MySQL, Postgres and SQLite
  • Simple schema migrations (+ automatic schema generation)
• Authentication
  • Cookie-based authentication (using gorilla/securecookie)
  • API key authentication (via header or query param)
• Configuration
  • YAML configuration
  • Environment variables
• Mailing
  • HTML templates
  • SMTP integration
  • MailWhale integration
• User Interface
  • Plain Go HTML templates
  • CSS styling with TailwindCSS
  • Icons with Iconify
  • Simple data binding with petite-vue
  • Pre-compressed assets using Brotli (see wakapi#284)
• Prometheus metrics exports
• Swagger API docs
• Unit Testing
• Docker support

Currently not included

• Multi-tenancy
• Advanced authorization mechanisms / RBAC
• API testing (see wakapi/testing, though)

🧂 Ingredients

• Web server: net/http (stdlib)
• Routing: gorilla/mux
• Database / ORM: gorm.io/gorm
• Templating: html/template (stdlib)
• Configuration: jinzhu/configor
• Logging: emvi/logbuch
• Event bus: leandro-lugaresi/hub
• Caching: patrickmn/go-cache
• Styling: tailwindlabs/tailwindcss
• Data binding: vuejs/petite-vue

🏃‍♀️ Run

Prerequisites

• Go >= 1.16
• Node.js >= 14 LTS
• gcc (to compile go-sqlite3)
  • Fedora / RHEL: dnf install @development-tools
  • Ubuntu / Debian: apt install build-essential
  • Windows: See here

Compile & Run

# Fetch node modules
$ yarn

# Build web assets
$ yarn build:all:compress

# Build the executable
$ go build -o broilerplate

# Adapt config to your needs
$ cp config.default.yml config.yml
$ vi config.yml

# Run it
$ ./broilerplate

🔧 Configuration Options

You can specify configuration options either via a config file (default: config.yml, customizable through the -c argument) or via environment variables. Here is an overview of all options.

YAML Key / Env. Variable	Default	Description
env / ENVIRONMENT	dev	Whether to use development- or production settings
app.avatar_url_template	(see config.default.yml)	URL template for external user avatar images (e.g. from Dicebear or Gravatar)
server.port / BROILERPLATE_PORT	3000	Port to listen on
server.listen_ipv4 / BROILERPLATE_LISTEN_IPV4	127.0.0.1	IPv4 network address to listen on (leave blank to disable IPv4)
server.listen_ipv6 / BROILERPLATE_LISTEN_IPV6	::1	IPv6 network address to listen on (leave blank to disable IPv6)
server.listen_socket / BROILERPLATE_LISTEN_SOCKET	-	UNIX socket to listen on (leave blank to disable UNIX socket)
server.timeout_sec / BROILERPLATE_TIMEOUT_SEC	30	Request timeout in seconds
server.tls_cert_path / BROILERPLATE_TLS_CERT_PATH	-	Path of SSL server certificate (leave blank to not use HTTPS)
server.tls_key_path / BROILERPLATE_TLS_KEY_PATH	-	Path of SSL server private key (leave blank to not use HTTPS)
server.base_path / BROILERPLATE_BASE_PATH	/	Web base path (change when running behind a proxy under a sub-path)
security.password_salt / BROILERPLATE_PASSWORD_SALT	-	Pepper to use for password hashing
security.insecure_cookies / BROILERPLATE_INSECURE_COOKIES	false	Whether or not to allow cookies over HTTP
security.cookie_max_age / BROILERPLATE_COOKIE_MAX_AGE	172800	Lifetime of authentication cookies in seconds or 0 to use Session cookies
security.allow_signup / BROILERPLATE_ALLOW_SIGNUP	true	Whether to enable user registration
security.expose_metrics / BROILERPLATE_EXPOSE_METRICS	false	Whether to expose Prometheus metrics under /api/metrics
db.host / BROILERPLATE_DB_HOST	-	Database host
db.port / BROILERPLATE_DB_PORT	-	Database port
db.user / BROILERPLATE_DB_USER	-	Database user
db.password / BROILERPLATE_DB_PASSWORD	-	Database password
db.name / BROILERPLATE_DB_NAME	app_db.db	Database name
db.dialect / BROILERPLATE_DB_TYPE	sqlite3	Database type (one of sqlite3, mysql, postgres, cockroach)
db.charset / BROILERPLATE_DB_CHARSET	utf8mb4	Database connection charset (for MySQL only)
db.max_conn / BROILERPLATE_DB_MAX_CONNECTIONS	2	Maximum number of database connections
db.ssl / BROILERPLATE_DB_SSL	false	Whether to use TLS encryption for database connection (Postgres and CockroachDB only)
db.automgirate_fail_silently / BROILERPLATE_DB_AUTOMIGRATE_FAIL_SILENTLY	false	Whether to ignore schema auto-migration failures when starting up
mail.enabled / BROILERPLATE_MAIL_ENABLED	true	Whether to allow BROILERPLATE to send e-mail (e.g. for password resets)
mail.sender / BROILERPLATE_MAIL_SENDER	[email protected]	Default sender address for outgoing mails (ignored for MailWhale)
mail.provider / BROILERPLATE_MAIL_PROVIDER	smtp	Implementation to use for sending mails (one of [smtp, mailwhale])
mail.smtp.* / BROILERPLATE_MAIL_SMTP_*	-	Various options to configure SMTP. See default config for details
mail.mailwhale.* / BROILERPLATE_MAIL_MAILWHALE_*	-	Various options to configure MailWhale sending service. See default config for details

👏 Support

Coding in open source is my passion and I would love to do it on a full-time basis and make a living from it one day. So if you like this project, please consider supporting it 🙂. You can donate either through buying me a coffee or becoming a GitHub sponsor. Every little donation is highly appreciated and boosts my motivation to keep improving!

📓 License

MIT