Commit 29ed642f authored by Julien Schröter's avatar Julien Schröter

Provide current information about how to setup and configure the server

parent 8b483807
Pipeline #1803 passed with stage
in 14 minutes and 21 seconds
# akamu-app-server
# Akamu App-Server
Backend REST API of the Akamu App.
Backend RESTful API of the Akamu App.
Documented in `appapi.yaml`. Hosted live at for master branch and for dev branch.
The API is documented in the file `appapi.yaml`.
There is a staging server hosted at as documented in which is deployed from the development branch. A stable version of the app server can be found at as documented in which is deployed from the master branch.
## Usage
The server requires a database connection.
The connection details have to be specified in a json configuration file `config.json`. That is placed in the top level directory.
The server can be started in _development_ or _production_ mode.
Production mode is the default.
_Development mode_ can be enabled by setting `-d` flag.
## Setup the Environment
All configurations can either be set throught the `config.json`, cli-flags or environment variables.
Independent from your environment, you need to have the dependencies installed. Run `go get ./...` to receive the go packages.
As a general advice one should use the config.json for developing and provide configuration through the command line when deploying..
Setup your MariaDB instance. Create a new database with the schema found in
First, install `akamuschema.sql`, containing the tables and procedures, then continue with `gamesettings.sql` and `deploydata.sql`.
## Configuration
### Development
The configuration files for the server are located under `/config`.\
In _development mode_ the file `dev.json` is used. Otherwise `prod.json` will be loaded.
For development, you can additionally install sample data. Sample data can be found in this project, in `/resources/data/testdata.sql`. This will create the users `user1` to `user5` with the passwords `Password1` to `Password5`. The passwords are hashed using the bcrypt algorithm.
To create your own configuration in `/config` and name it `dev.json`.
Have a look at `prod.json` as a reference.
### Configuration
It could make sense to provide the database password for local development purposes.
To do so specify the property `database.password` in the json configuration.
There are several ways to configure the game server. This section will cover the different ways to configure the game server.
**Important:** Do not write a password into the `prod.json`! When running in production mode always pass the password as command line argument.
To run the server, you need at least to provide a configuration for the database. Redundant configuration will be treated in the following order: Console Arguments > Environment Variables > Configuration File. The values read from password files or a file containing the jwt secret will overwrite the values passed directly using the mentioned ways to configure the server.
#### Example development configuration
#### SMTP
To send emails, you need to provide SMTPS credentials to the server application. Note that emails can only be sent using SSL/TLS.
#### Push Notifications
## Development
For push notifications, Google Firebase Cloud Messaging is used. To enable push notifications, create a firebase project, place your private key on your server and provide the path to that private key using the `GOOGLE_APPLICATION_CREDENTIALS` environment variable. Make sure that your clients also support push notifications using Firebase Cloud Messaging.
### Run
First install needed dependencies
For more details about how to setup Firebase, see
go get ./...
#### Error Tracking
Run the server using commandline with
The Game Server uses Sentry's Raven for error tracking. Provide the DSN using the `SENTRY_DSN` environment variable to enable error tracking.
go run main.go setup.go --dev
For more details about how to setup Raven, see
Alternativly you can build the project using
#### Password Files
go build
The Server allows you to provide the password for the database, the resource server, smtp and jwt secret using dedicated files. Just create a file for the password or secret you want to provide this way and provide just the password or secret in it without any other formatation. Then provide the path to the file using the `jwt-file` or `pwfile` options of the server's configuration instead of the value directly.
and run the created executable with parameter --dev or -d. Make sure a config/dev.json configuration file exists in your working directory either way.
When you run the server without the `-d` flag, you cannot pass the database password and the jwt secret directly to the server, instead you must provide a file with the database password and a file with the jwt password.
### Open API Specification 3
#### Environment Variables
The API is specified using [OAS3](
Subsequently before making any change to the API, make sure to change the specification `appapi.yaml` first.
You can provide the path to the database password file in the environment variable `PWFILE`.
You can provide the path to the file containing the jwt secret in the environment variable `JWTFILE`.
You can provide the port, the server should be running on using the environment variable `PORT`.
After editing you can validate the specification using either the [swagger webeditor](, the [python openapi validator]( or any other tool that you can find.
#### Configuration File
openapi-spec-validator appapi.yaml
You can provide the configuration using a configuration file, which must be named `/config.json` and must right in the root of the working directory.
### Guide
Use the following as template for your `config.json` and remove the inapplicable fields.
Steps for adding a new Endpoint:
"jwt-secret": "SECRET",
"jwt-file": "/path/to/file/with/secret",
"database": {
"user": "USERNAME",
"host": "HOSTNAME",
"password": "PASSWORD",
"pwfile": "/path/to/file/with/database/password"
"resource-server": {
"host": "HOSTNAME",
"user": "USERNAME",
"password": "PASSWORD",
"pwfile": "/path/to/file/with/resource-server/password"
"smtp": {
"hostname": "HOSTNAME",
"username": "USERNAME",
"password": "PASSWORD",
"port": 465
1. Understand and define the requirements for the endpoint.
This includes defining the url endpoint to be called as well as the proper http request type,
parameters, body, and all possible responses.
Once the endpoint specification has been defined by the team, the endpoint specification can be written down in the OpenAPI3 specification.
This is done in the appapi.yaml file.
2. Implement all required SQL tables and update the akamuschema.sql and testdata.sql
3. If needed, define new group routes in setup.go.
New routes are needed if the endpoint does not belong to existing endpoint groups.
Have a look at existing endpoint groups and discuss with other developers if a new group is required or not.
4. Create a domain package with the files endpoint.go, query.go and request.go in the endpoint package. request.go is supposed to contain structs with request parameters. On the attributes you can also set tags. The `required` tag ensures that a
`ctx.ShouldBind(&struct)` throws an error if the request does not provide the attribute in the json body or in the query parameter. The `json` and `form` tags
tell methods such as `ctx.ShouldBind(&struct)` what names they must look for while trying to retrieve the data that maps to the attribute. `json` from json bodies and `form` from query parameters.
This is specially helpful while programming in go, since go's naming convention enforces most attributes to start with capital letters, while json objects have lower caps attributes. Using the tag `json:"name"` on a `Name string` attribute, it is possible to bind
a json parameter called `name` to a struct attribute called `Name`, otherwise `ctx.ShouldBind(&struct)` would not understand that name maps to Name.
Implement business logic for each route in the related endpoint.go file and use query.go to abstract database access in high-level functions.
Notice that the `jwt-file` and the `database.pwfile` fields, if present, will overwrite the values set using the environment variables.
## Deployment
#### Console Arguments
Build the project using `go build` command.
You can pass most parameters, such as for the configuration of the database, smtp, the resource server and the jwt secret as console arguments. Call the executable just with the `-help` parameter to see the which options are available and how to use them.
When deploying for production, provide the password using a password file.
Note that these arguments overwrite the values you provided using the other ways.
Do not provide any database password in config/prod.json since this could be a potential risk.
## Run the Server
If you provide the password as command line argument you should make sure you clear the command line history of your operating system.
The server can be started using `go run main.go` or by running the executable which can be build by `go build`. Make sure to provide the configuration. You need to have the `/assets/` directory right in the working directory.
The best way to supply a password is through a pwfile that is deleted after the server has started.
For development purposes, start the server with `-d` parameter. This will set Gin to debug mode and allows the database password and the jwt secret to be provided directly using the default configuration file or console arguments.
Further information on deployment is found in the wiki on Access is restricted to Akamu Members.
\ No newline at end of file
## Build the Server
To build the server run `go build` after you installed the server's dependencies.
## Further Information
You can find further information about the server or Akamu itself in our wiki at or from us in person.
Contact us at []( and join our team.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment