This repository holds the following components:
api
- the proto API definition in theCampusService.proto
.client
- example client for how to connect to the backend.server
- the actual server implementation serving both REST at api.tum.app and gRPC endpoints at api-grpc.tum.app.
The API is publicly available for anyone, but most notably, it's the main backend system for the TUM Campus Apps (Android, iOS, and Windows).
The backend uses MySQL as its backend for storing data. In the following, we provide instructions for installing MariaDB as the DB server of choice.
sudo dnf install mariadb-server
# Start the MariaDB server
sudo systemctl start mariadb
# Optional: Enable autostart
sudo systemctl enable mariadb
More details are available here: https://docs.fedoraproject.org/en-US/quick-docs/installing-mysql-mariadb/
sudo apt install mariadb-server
# Start the MariaDB server
sudo systemctl start mariadb
# Optional: Enable autostart
sudo systemctl enable mariadb
To setup the DB, connect to your DB server or use mysql
to connect to it locally.
DROP DATABASE campus_backend; -- Drop an eventually existing old DB
CREATE DATABASE campus_backend; -- Create a new DB for the backend
CREATE USER 'gorm'@'localhost' IDENTIFIED BY 'gorm'; -- Create a new user called `gorm`.
GRANT ALL PRIVILEGES ON campus_backend.* TO 'gorm'@'localhost'; -- Garant our `gorm` user access to the `campus_backend` DB.
ALTER USER 'gorm'@'localhost' IDENTIFIED BY 'GORM_USER_PASSWORD'; -- Set a password for the `gorm` user.
FLUSH PRIVILEGES;
To start the server there are environment variables, as well as command line options available for configuring the server behavior.
cd server
export DB_DSN="Your gorm DB connection string for example: gorm:GORM_USER_PASSWORD@tcp(localhost:3306)/campus_backend"
go run ./main.go
There are a few environment variables available:
- [REQUIRED]
DB_DSN
: The GORM DB connection string for connecting to the MySQL DB. Example:gorm@tcp(localhost:3306)/campus_backend
- [OPTIONAL]
SENTRY_DSN
: The Sentry Data Source Name for reporting issues and crashes.
docker compose up -d
The docker compose will start the server and a mariadb instance.
The server will be available at localhost:50051
and the mariadb instance at localhost:3306
.
Additionally, docker creates the volume campus-db-data
and campus-influxdb-data
to persist the data of the mariadb and influxdb instances.
The mariadb schema can be installed by executing the following command inside the mariadb container:
mysql --user=root --password=secret_root_password campus_db < /entrypoint/schema.sql
The following environment variables need to be set for the server to work properly:
- [REQUIRED]
DB_NAME
: The name of the database to use. - [REQUIRED]
DB_ROOT_PASSWORD
: The password of the root user. - [OPTIONAL]
DB_PORT
: The port of the database server. Defaults to3306
. - [OPTIONAL]
SENTRY_DSN
: The Sentry Data Source Name for reporting issues and crashes. - InfluxDB [OPTIONAL]:
- [OPTIONAL]
INFLUXDB_USER
: The InfluxDB username to set for the systems initial superuser. - [OPTIONAL]
INFLUXDB_PASSWORD
: The InfluxDB password to set for the systems initial superuser. - [OPTIONAL]
INFLUXDB_ORG
: The InfluxDB organization to set for the systems initial organization. - [OPTIONAL]
INFLUXDB_BUCKET
: The InfluxDB bucket to set for the systems initial bucket. - [REQUIRED]
INFLUXDB_URL
: The InfluxDB URL to use for writing metrics. - [REQUIRED]
INFLUXDB_ADMIN_TOKEN
: The InfluxDB admin token to use for authenticating with the InfluxDB server. If set initially the system will associate the token with the initial superuser.
- [OPTIONAL]
- iOS Push Notification Service [OPTIONAL]:
- [REQUIRED]
APNS_KEY_ID
: The key ID of the APNs key => APNs Key needs to be downloaded from the Apple Developer Portal the name of the file also contains the key ID. - [REQUIRED]
APNS_TEAM_ID
: The team ID of the iOS app can be found in AppStoreConnect. - [REQUIRED]
APNS_P8_FILE_PATH
: The path to the APNs key file (e.g./secrets/AuthKey_XXXX.p8
) in the docker container. The file itself needs to exist in the same directory as thedocker-compose.yml
file and calledapns_auth_key.p8
.
- [REQUIRED]
InfluxDB can be used to store metrics.
If an InfluxDB instance is already set up, just the INFLUXDB_URL
and the INFLUXDB_ADMIN_TOKEN
environment variable needs to be set
to enable the metrics endpoint.
All the other environment variables are optional and only needed if the InfluxDB instance needs to be set up.
If INFLUXDB_URL
or INFLUXDB_ADMIN_TOKEN
are not set, the metrics endpoint will be disabled.
The iOS Push Notifications Service can be used to send push notifications to iOS devices.
There are already predefined Visual Studio Code launch tasks for debugging the client and server.
Take a look at the lauch.json
file for more details.
Please be respectful with its usage!
To ensure that that common pitfalls which can be automated are not done, we recommend you to install pre-commit
.
You can do so via
python -m venv venv
source venv/bin/activate
pip install pre-commit
pre-commit install
Certain pre-commit
hooks will now be run on every commit where you change specific files.
If you want to run all files instead, run pre-commit run -a