Go Webapp Example

This repo contains an example structure for a monolithic Go Web Application.

You can read more details about this project on our blog: https://offline.ch/blog/go-applikations-architektur (german article)

Architecture

This project loosely follows Uncle Bob's Clean Architecture.

Other inspirations:

• https://github.com/golang-standards/project-layout
• https://pace.dev/blog/2018/05/09/how-I-write-http-services-after-eight-years
• https://github.com/MichaelMure/git-bug/tree/master/graphql/schema

Features

It includes the following features:

• Magefiles
• Database migrations
• Configuration
• Data Seeder (Prod and Test)
• Live reloading
• Linting
• GraphQL Server
• User sessions
• Role-based Access control
• One-time update routines
• I18N
• Background processes (Daemons)
• Unit and Integration tests

Disclaimer

The whole project is tailored to our very specific needs for our CareSuite software product. CareSuite is deployed via Docker as a monolithic application. It is not optimized for cloud deployments. While it might not fit your exact needs it can be a good inspiration when building a new application.

Authentication

All authentication has been disabled, so you can test the server without having to log in.

Remove the if true {} block in internal/pkg/auth/auth.go:116 to require a session to access the backend server.

You can login with a POST request to /backend/login. You need to send a username and password value (by default both are set to admin).

Get up and running

Use Mage to run common tasks:

Start the Docker stack

A MySQL server can be started using

mage -v run:docker

Start the server in live reloading mode

To start the backend server, run

mage -v run:backend

If you make changes to the code, the binary will be rebuilt.

Visit the GraphQL Playground

Once the Docker stack and the backend server are running, visit http://localhost:8888/backend/graphql-playground in your browser.

You can run the following query to test your installation:

query {
  quotes {
    id
    content
    author
  }
  
  quote (id: 1) {
    id
    content
    author
  }
  
  users {
    id
    name
    roles {
      id
      name
      permissions {
        code
        level
      }
    }
  }
}

Or create some data and check the auditlogs table afterwards:

mutation {
  createQuote (input: {
    author: "Me"
    content: "Something nice"
  }) {
    id
    author
    content
  }
}

Run the linter

To lint all backend code, run

mage -v lint:backend

Run tests

To run tests, use

# Run only unit tests
mage -v test:backend
# Run unit and integration tests
mage -v test:integration

Run code generator

To rebuild the GraphQL server and all dataloaders, run

mage -v run:generate

Other mage tasks

Run mage without any arguments to get a list of all available tasks. These tasks are stored in the magefile.go.

Change the configuration

The whole application is configured using the config.toml file. Change it so it fits your needs.

Build the docker image

Run the following command from the project's root directory:

docker build -t go-webapp-example -f build/docker/Dockerfile .

Command line interface

You can use the following commands afters building the binary using go build.

Run database migrations

Use the migrate command to manage the database migrations.

# Run missing migrations
./go-webapp-example migrate up
# Destroy database and start new
./go-webapp-example migrate fresh
# Show current version
./go-webapp-example migrate version

Seed data

Use the seed command to populate the database with initial seed data.

./go-webapp-example seed

Start the server

Use the serve command to start the backend server without live reloading.

./go-webapp-example serve

Show version information

Use the version command to show version information.

./go-webapp-example version