Self-hosting Guide

Get ShareAux running on your own server in under 10 minutes.

1. Requirements

Linux server (Ubuntu 22.04+ recommended) or any Docker-capable host
Docker + Docker Compose v2
A domain name (for HTTPS)
Ports 80/443 open

2. Install

git clone https://github.com/Protomothis/ShareAux.git
cd ShareAux
cp .env.example .env

3. Environment Variables

Edit .env — at minimum, change these:

Variable	Description	Example
`DB_PASSWORD`	PostgreSQL password	`my-secure-password`
`JWT_SECRET`	Random string for token signing	`openssl rand -hex 32`
`CLIENT_URL`	Your public URL	`https://music.example.com`

Optional variables:

Variable	Description
`GOOGLE_CLIENT_ID`	Google OAuth (login with Google)
`GOOGLE_CLIENT_SECRET`	Google OAuth secret
`GOOGLE_CALLBACK_URL`	`https://your-domain/api/auth/google/callback`
`GEMINI_API_KEY`	Lyrics AI translation (Gemini)
`CAPTCHA_ENABLED`	PoW CAPTCHA (default: true)

4. HTTPS (Reverse Proxy)

ShareAux exposes port 8080 via its internal Caddy gateway. You need an external reverse proxy on the host for HTTPS.

With Caddy (recommended)

Install Caddy on the host and create /etc/caddy/Caddyfile:

music.example.com {
    reverse_proxy localhost:8080
}

Caddy auto-provisions Let's Encrypt certificates. That's it.

With Nginx

server {
    server_name music.example.com;
    listen 443 ssl;
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
    }
}

Important: WebSocket (/ws) requires Upgrade headers. The examples above handle this.

Set CLIENT_URL in .env to your public URL (e.g. https://music.example.com).

5. Start

docker compose up -d

Check status:

docker compose ps
docker compose logs -f

Access your site at https://music.example.com

6. Google OAuth (Optional)

Go to Google Cloud Console
Create OAuth 2.0 Client ID (Web application)
Authorized redirect URI: https://your-domain/api/auth/google/callback
Copy Client ID and Secret to .env
Restart: docker compose restart server

Without Google OAuth, users can still log in with username/password or guest invite codes.

Visit your site and create an account
The first registered user automatically becomes Super Admin
Access the admin panel at /admin
Configure settings, create rooms, and invite others

8. Updating

cd ShareAux
docker compose pull
docker compose up -d

Database migrations run automatically on startup.

← Back to Home