Operations & Maintenance

import { Steps } from ‘@astrojs/starlight/components’;

This guide covers operational workflows for maintaining and troubleshooting self-hosted brūhi Cloud instances on production Linux servers (AWS EC2, Lightsail, DigitalOcean, Hetzner, Linode, or any Linux VPS).

---

Updating to the Latest Version

Configuration updates

Always update docker-compose.yml before pulling the new image when a new release is announced.

Production instances initialized via install.sh do not use git pull because the deployment directory (~/bruhi-cloud) is not a Git repository. Use curl to refresh configuration files.

1. Refresh docker-compose.yml

   cd ~/bruhi-cloud
   curl -fsSL https://raw.githubusercontent.com/bruhi-technologies/bruhi-deploy/main/docker-compose.yml -o docker-compose.yml

2. Pull the Latest Image and Restart

   # Pull the updated container image
   docker compose pull
   
   # Recreate containers with zero-downtime transition
   docker compose up -d

3. Verify Startup

   docker compose ps
   docker compose logs --tail=30 bruhi-cloud

   You should see:

   INFO:     Application startup complete.
   INFO:     Uvicorn running on http://0.0.0.0:8000

---

Checking Server Status & Health

Verify service health via Docker and the /healthz HTTP endpoint:

cd ~/bruhi-cloud

# Check container status
docker compose ps

# Test health check endpoint
curl -i http://localhost:8000/healthz

Expected response:

HTTP/1.1 200 OK
content-type: application/json

{"status": "ok"}

---

Viewing Logs

cd ~/bruhi-cloud

# Stream live logs from all services (FastAPI, Rust engine, Caddy, Icecast)
docker compose logs -f

# Stream only the brūhi Cloud API and audio engine
docker compose logs -f bruhi-cloud

# Stream only Icecast logs
docker compose logs -f icecast

# View the last 100 log lines
docker compose logs --tail=100 bruhi-cloud

---

User & Admin Account Management

Reset Password via Built-in CLI Script

brūhi Cloud includes a reset_password.py script inside the container. Use it to reset any user’s password without directly modifying the SQLite database:

docker compose exec bruhi-cloud python3 /app/server/reset_password.py [email protected] new_password_here

Expected output:

Success: Password for '[email protected]' reset successfully.

Pre-seeding Admin Account on First Boot

When deploying a brand new instance, you can pre-seed the initial owner account in your .env file before first launch:

BRUHI_ADMIN_EMAIL[email protected]
BRUHI_ADMIN_PASSWORD=your_secure_password

Start the container normally (docker compose up -d). The account is created on initial boot. After logging in, remove these lines from .env.

Resetting All Users

To clear all users and re-trigger the initial first-run setup wizard:

docker compose exec bruhi-cloud python3 -c "
import sqlite3
conn = sqlite3.connect('/app/data/bruhi.db')
conn.execute('DELETE FROM users')
conn.commit()
print('All users deleted.')
"
docker compose restart bruhi-cloud

---

Icecast Streaming Password Management

Changing Passwords

1. Edit your .env file:

   cd ~/bruhi-cloud
   nano .env

2. Update the credentials:

   ICECAST_SOURCE_PASSWORD=new_strong_source_password
   ICECAST_ADMIN_PASSWORD=new_strong_admin_password
   ICECAST_RELAY_PASSWORD=new_strong_relay_password

3. Restart containers to apply:

   docker compose up -d

Note

After changing ICECAST_SOURCE_PASSWORD, update any station output configurations in the dashboard via Admin → Stations → Outputs to use the new source password.

---

Clean Reset & Volume Maintenance

Data Loss Warning

docker compose down -v permanently deletes all station configs, user accounts, playlists, and uploaded audio files.

Full Wipe / Clean Re-install

cd ~/bruhi-cloud
docker compose down -v
docker compose up -d

Reset Database Only (Preserve Uploaded Audio)

To wipe stations, playlists, and accounts while keeping all uploaded MP3/WAV files:

cd ~/bruhi-cloud
docker compose down
docker volume rm bruhi-cloud_bruhi_db
docker compose up -d

---

Useful Commands Cheat Sheet

Task	Command
Check container health	docker compose ps
Follow live application logs	docker compose logs -f bruhi-cloud
Restart brūhi service	docker compose restart bruhi-cloud
Inspect SQLite DB interactively	docker compose exec bruhi-cloud sqlite3 /app/data/bruhi.db
List registered users via Python	docker compose exec bruhi-cloud python3 -c "import sqlite3; conn=sqlite3.connect('/app/data/bruhi.db'); [print(r) for r in conn.execute('SELECT id, email, role FROM users')]"
Enter container shell	docker compose exec bruhi-cloud bash
Test Icecast status page	curl http://localhost:8010/status.xsl