Commit 71d58deb authored by Frederik Wegner's avatar Frederik Wegner

updated README

parent e68fb4a7
Pipeline #1756 passed with stages
in 22 minutes and 49 seconds
# akamu-app-server
## Usage
Backend REST API of the Akamu App.
Documented in `appapi.yaml`. Hosted live at https://akamu.de/api/docs/#/ for master branch and https://dev.akamu.de/api/docs/#/ for dev branch.
## Usage
The server requires a database connection.
The connection details have to be specified in a configuration file under `/config`.\
The server can be started in development or production mode.
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.
A database information can be passed through the command line parameters:
-d Set true for debugging purposes, alternative to --dev
-database string
Overwrite database name (default "akamu")
-dbpassword string
Overwrite the password specified in database configuration.
Required for production instance (default "alalalal")
-host string
Overwrite the hostname specified in database configuration (default "localhost")
-pwfile string
Overwrite optional password file path specified in database configuration.
Also overwrites PWFILE environment variable
-user string
Overwrite the user specified in database configuration (default "akamu")
All configurations can either be set throught the `config.json`, cli-flags or environment variables.
As a general advice one should use the config.json for developing and provide configuration through the command line when deploying..
......@@ -48,38 +33,43 @@ To do so specify the property `database.password` in the json configuration.
`config/dev.json`
{
"database": {
"host": "",
"name": "akamu",
"user": "akamu",
"password": "*****"
"secret":"akamu",
"database":{
"name":"akamu_test",
"user":"akamuuser",
"host":"akamudbhost",
"password":"akamu"
},
"resource-server":{
"host":"some-url",
"user":"user1",
"password":"password1"
}
}
## Development
### Run
First install needed dependencies
go get ./...
Run the server using commandline with
```
go run main.go setup.go --dev
```
Alternativly you can build the project using
```
go build
```
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.
### Open API Specification 3
The API is specified using [OAS3](https://github.com/OAI/OpenAPI-Specification).
Subsequently before making any change to the API, make sure to change the specification first.
Subsequently before making any change to the API, make sure to change the specification `appapi.yaml` first.
After editing you can validate the specification using either the [swagger webeditor](https://editor.swagger.io) or the [python openapi validator](https://github.com/p1c2u/openapi-spec-validator).
After editing you can validate the specification using either the [swagger webeditor](https://editor.swagger.io), the [python openapi validator](https://github.com/p1c2u/openapi-spec-validator) or any other tool that you can find.
openapi-spec-validator appapi.yaml
......@@ -112,3 +102,7 @@ When deploying for production, provide the password using a password file.
Do not provide any database password in config/prod.json since this could be a potential risk.
If you provide the password as command line argument you should make sure you clear the command line history of your operating system.
The best way to supply a password is through a pwfile that is deleted after the server has started.
Further information on deployment is found in the wiki on confluence.akamu.de. Access is restricted to Akamu Members.
\ No newline at end of file
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