Skip to main content

Get Started

Prerequisites​

Before you begin, make sure your system meets the following requirements.

System Requirements​

Uni-Verein runs on very modest hardware. The minimum is a Raspberry Pi 3, for everyday use we recommend a bit more power.

MinimumRecommended
HardwareRaspberry Pi 3Current mini PC, server, or VPS
RAM1 GB2 GB or more
CPU4 cores (Raspberry Pi 3)2 or more cores of a current processor

ℹ️ On a Raspberry Pi 3 the software is perfectly usable. Only the login takes noticeably longer there, after that the application responds smoothly. If that bothers you or many people work at the same time, go with the recommended specs.

Required Software​

  • Docker & Docker Compose – to run the application
  • Install Docker
  • Docker Compose is already included with Docker Desktop
  • curl – to download the configuration files (preinstalled on most systems)
  • A domain whose DNS A/AAAA record points to your server's public IP address
  • Ports 80 and 443 must be reachable from the internet (check your firewall, cloud security group, and router port forwarding). Port 80 is required even for HTTPS, because it is used to issue the certificate and to redirect plain HTTP visitors to HTTPS

Step 1: Install Docker​

If Docker is not yet installed, download it from the official website and install it:

👉 https://docs.docker.com/get-docker/

After installation, verify that Docker is working correctly:

docker --version
docker compose version

Step 2: Install and Run the Project​

Choose one of the two options. What matters is whether something in front of Uni-Verein already handles HTTPS encryption (e.g. a load balancer from your host, a Cloudflare Tunnel, or an existing reverse proxy).

Use this option unless you already handle encryption in front of Uni-Verein. A free Let's Encrypt certificate is obtained and renewed automatically, Caddy is included for this.

  1. Download the configuration and installation files
curl -O https://raw.githubusercontent.com/uni-verein/uni-verein/main/nginx.conf
curl -O https://raw.githubusercontent.com/uni-verein/uni-verein/main/Caddyfile
curl -O https://raw.githubusercontent.com/uni-verein/uni-verein/main/docker-compose-ini.yml
curl -O https://raw.githubusercontent.com/uni-verein/uni-verein/main/docker-compose-tls.yml
  1. Generate the environment variables in the .env file
touch .env && mkdir backup && docker compose -f docker-compose-ini.yml up

Edit the .env file, change the database passwords, and enter your domain:

DB_ROOT_PASSWORD=rootUserPassword
DB_NAME=uni-verein
DB_USER=databaseUserName
DB_PASSWORD=databaseUserPassword
DOMAIN=verein.example.org
ACME_EMAIL=admin@example.org

DOMAIN is the address under which Uni-Verein should be reachable. ACME_EMAIL is registered with Let's Encrypt for notices about the certificate.

  1. Start the application
docker compose -f docker-compose-tls.yml up -d

The application will then be accessible at https://<your-domain>. 🎉 The certificate is requested automatically on first start, which can take up to a minute. This requires the DNS record and open ports 80/443. If the page doesn't show up, check Caddy's logs:

docker compose -f docker-compose-tls.yml logs caddy

Option B: HTTPS is already handled in front of Uni-Verein​

⚠️ Only use this option if encryption is really already set up in front of Uni-Verein. This path serves plain HTTP with no encryption of its own. Exposing it directly to the internet sends credentials, session tokens, and member data (including IBANs) in the clear.

  1. Download the configuration and installation files
curl -O https://raw.githubusercontent.com/uni-verein/uni-verein/main/nginx.conf
curl -O https://raw.githubusercontent.com/uni-verein/uni-verein/main/docker-compose-ini.yml
curl -O https://raw.githubusercontent.com/uni-verein/uni-verein/main/docker-compose-prod-image.yml
  1. Generate the environment variables in the .env file
touch .env && mkdir backup && docker compose -f docker-compose-ini.yml up

Edit the .env file and change the database passwords:

DB_ROOT_PASSWORD=rootUserPassword
DB_NAME=uni-verein
DB_USER=databaseUserName
DB_PASSWORD=databaseUserPassword
  1. Start the application
docker compose -f docker-compose-prod-image.yml up -d

The application will then be accessible at http://localhost:80. 🎉

ℹ️ As of version 1.4.0, Uni-Verein uses PostgreSQL instead of MariaDB as its database engine. A fresh install using the files above sets up PostgreSQL directly; the .env variable names stay the same.

Checking containers and logs​

To check the running containers (use -f docker-compose-tls.yml for Option A, -f docker-compose-prod-image.yml for Option B):

docker compose -f docker-compose-tls.yml ps

To view the logs:

docker compose -f docker-compose-tls.yml logs -f

Step 3: First Login​

After starting, you can sign in with the prepared administrator account:

  • User: Admin
  • Password: admin123

⚠️ This is a well-known default password. Logging in with it opens a dialog that can't be dismissed until you have set a new password. Only then can you use the application.

To see how to continue, read the Quick Start.

Updating​

As an admin, you'll see a notification bell in the app once a new version is available. Before updating, create a manual backup (database backup and member export, both available under Settings → Backup in the app). Then run this from your installation directory (the one containing .env):

curl -O https://raw.githubusercontent.com/uni-verein/uni-verein/main/docker-compose-update.yml
docker compose -f docker-compose-update.yml run --rm update

It checks GitHub for the latest release and asks you to confirm that you've created a manual backup — the update only proceeds once you type yes. It then downloads the matching nginx.conf and the compose file of your installation (docker-compose-tls.yml plus Caddyfile for Option A, docker-compose-prod-image.yml for Option B), updates VERSION in your .env, and restarts the stack on the new version. Your existing secrets and database are left untouched.

ℹ️ The Caddyfile is overwritten on every update, just like nginx.conf. Local changes to it are lost. DOMAIN and ACME_EMAIL live in .env and are preserved.

⚠️ Important when updating to 1.8.1 or newer: Since 1.8.1, proxy and frontend listen on port 8080 inside the container (the host port stays 80), and all containers run without root privileges. Therefore always update with the command above, which replaces nginx.conf and the compose file together and prepares the logs/ and receipts/ directories. If you use self-enrollment, open the general settings once after the update and save them, so the public URL for the confirmation links is stored. Details are in the 1.8.1 blog post.

⚠️ Important if you're updating from before 1.4.0: As of version 1.4.0, Uni-Verein switches its database engine from MariaDB to PostgreSQL. Installations still on MariaDB are first brought to 1.3.1 automatically; the next update run then migrates the database to PostgreSQL and switches over the whole stack. This adds downtime proportional to your database size — rerun the update command as needed until it reports "Already up to date". See the 1.4.0 blog post for the full migration process and its safety net.

Last updated on