Installing on Your Server (Step by Step)

In this chapter you'll connect to your VPS, install the required tools, clone the middleware repository, install Python dependencies, and start the server. We'll also cover how to run the service in the background using systemd.

The examples assume a fresh Ubuntu LTS VM (22.04/24.04) with a public IP.

3.1 Connect to the Server via SSH

SSH is the standard secure way to log in to a Linux server from your computer.

Windows

The easiest tool is PuTTY (a free SSH client):

1. Install PuTTY and open it
2. Enter your server's public IP in "Host Name"
3. Set Port to 22, Connection type to SSH
4. Click Open
5. Log in with the username provided by your host (often root or ubuntu)

TIP

Prefer an SSH key over passwords whenever possible. PuTTY's key tool is called PuTTYgen.

macOS / Linux

Open the Terminal app and run:

ssh ubuntu@<YOUR_SERVER_IP>

Replace ubuntu with your image's default user (often root or ubuntu).

3.2 Update the System & Install Base Tools

Bring the system up to date and install Git, Python and virtual-env tooling:

sudo apt update && sudo apt -y upgrade
sudo apt -y install git python3 python3-venv python3-pip

INFO

If your VM uses the root user, omit sudo.

3.3 Create a Working Directory

Use /opt (conventional for custom apps) and make yourself the owner:

sudo mkdir -p /opt/bud-e
sudo chown -R "$USER":"$USER" /opt/bud-e
cd /opt/bud-e

3.4 Clone the Middleware Repository

Clone the official Admin Bud-E middleware repository:

git clone https://github.com/christophschuhmann/school-bud-e-middleware.git
cd school-bud-e-middleware

3.5 (Recommended) Create a Python Virtual Environment

A virtual environment (venv) keeps this app's Python packages isolated from the system Python, avoiding version conflicts.

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip

3.6 Install Python Dependencies

Install the packages listed by the repository (this may take a few minutes on first run):

pip install -r requirements.txt

3.7 Configure Environment (Admin Password, Ports, etc.)

Some builds expose configuration via environment variables. If your version supports an admin password variable, set it now (replace the value):

export ADMIN_PASSWORD="choose-a-strong-password"

INFO

If your version uses a different variable name or a setup prompt, follow the repository's README. You can also put exports into a file like /opt/bud-e/env.sh and source it before starting, or reference it from the systemd service (see below).

3.8 Start the Server (Foreground Test)

Run the app directly to verify it starts. Most builds expose a serve.py entry point:

python serve.py --host 0.0.0.0 --port 8000

Keep this terminal open. From your browser visit http://<YOUR_SERVER_IP>:8000/admin.

You should see the Admin Bud-E login. If that works, stop the server with Ctrl+C.

3.9 Optional: Reverse Proxy & HTTPS (Caddy or Nginx)

For production you'll want a proper domain and HTTPS. The most convenient approach is a reverse proxy (Caddy or Nginx) in front of port 8000. Both can obtain TLS certificates automatically via Let's Encrypt.

• Caddy install – very simple automatic HTTPS
• Nginx + Certbot – popular alternative

TIP

Open ports 80 and 443 in your cloud firewall and/or ufw.

3.10 Run as a Service with systemd

This keeps the server running in the background and restarts it on reboot.

Step 1: Create an Environment File (Optional but Handy)

cat <<'EOF' | sudo tee /opt/bud-e/env.sh
export ADMIN_PASSWORD="choose-a-strong-password"
export BIND_HOST="0.0.0.0"
export BIND_PORT="8000"
EOF

sudo chown root:root /opt/bud-e/env.sh
sudo chmod 600 /opt/bud-e/env.sh

Step 2: Create the systemd Unit

cat <<'EOF' | sudo tee /etc/systemd/system/admin-bude.service
[Unit]
Description=Admin Bud-E (middleware)
After=network.target

[Service]
Type=simple
User=%i
WorkingDirectory=/opt/bud-e/school-bud-e-middleware
EnvironmentFile=/opt/bud-e/env.sh
ExecStart=/opt/bud-e/school-bud-e-middleware/.venv/bin/python serve.py --host ${BIND_HOST:-0.0.0.0} --port ${BIND_PORT:-8000}
Restart=on-failure

[Install]
WantedBy=multi-user.target
EOF

INFO

If you don't use a venv, replace the ExecStart Python path with /usr/bin/python3.

Step 3: Enable & Start

sudo systemctl daemon-reload
sudo systemctl enable --now admin-bude.service
sudo systemctl status admin-bude.service

Visit http://<YOUR_DOMAIN_OR_IP>:8000/admin (or your proxy's HTTPS URL).

3.11 Basic Hardening & Firewall

Use SSH Keys

Disable password login where possible.

Enable a Firewall

On Ubuntu:

sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

Set Up Monitoring

Set up simple uptime monitoring (e.g. UptimeRobot).

Next Steps

Configure Providers & Routes in the Admin UI, add pricing, and test a first request from the front end.