Installing VulaSocial with Docker
Operator guide
Installing VulaSocial with Docker
The repository ships a ready-to-run docker-compose.yml, Dockerfile and
.dockerignore. Docker is the fastest way to stand up a full node (app +
database + workers) on any server or VPS that has Docker Engine.
Prerequisites
- Docker Engine 24+ and Docker Compose v2
- A domain with DNS pointed at your server (for HTTPS)
- 2 GB RAM recommended
1. Clone & configure
git clone https://github.com/charlesash-za/vulasocial.git
cd vulasocial
cp .env.example .env
2. Set the essential environment values
Edit .env:
APP_ENV=production
APP_DEBUG=false
APP_URL=https://your-node.example
DB_CONNECTION=mysql
DB_HOST=mysql
DB_PORT=3306
DB_DATABASE=vulasocial
DB_USERNAME=vulasocial
DB_PASSWORD=change-me-strong-password
QUEUE_CONNECTION=database
CACHE_STORE=database
SESSION_DRIVER=database
BROADCAST_CONNECTION=log # switch to reverb for realtime (see the Realtime messaging article in Help)
FEDERATION_PUBLIC_BASE_URL=https://your-node.example
DB_HOSTmust be the Compose service name (mysql), not127.0.0.1.
3. Build & start
docker compose up -d --build
This starts:
- app — the PHP-FPM / web container serving VulaSocial
- mysql — the MariaDB/MySQL database
- queue — the queue worker (drains jobs)
4. Run first-time setup
docker compose exec app php artisan key:generate
docker compose exec app php artisan migrate --force
docker compose exec app php artisan storage:link
docker compose exec app php artisan optimize:clear
5. Create the admin user
See First-run setup. The simplest path is to register an account on your site, then promote it:
docker compose exec app php artisan tinker
$user = App\Models\User::where('email', 'you@example.com')->first();
$user->forceFill(['pending_approval' => false])->save();
Then assign the super_admin role in the admin panel (People & Access → Roles)
or via the RolesSeeder.
6. Reverse proxy / HTTPS
Docker Compose in this repo exposes the app on port 80/8080. Put a reverse proxy (Caddy, nginx, Traefik) in front for HTTPS, or bind a host port:
# docker-compose.yml (app service)
ports:
- "127.0.0.1:8080:80"
Then point your proxy at http://127.0.0.1:8080.
Useful commands
# View logs
docker compose logs -f app
# Run a queue worker manually (already a service, but useful when debugging)
docker compose exec app php artisan queue:work database --stop-when-empty
# Take the app down/up
docker compose down
docker compose up -d
Updating
git pull
docker compose up -d --build
docker compose exec app php artisan migrate --force
docker compose exec app php artisan optimize:clear
See Updating an existing node for the full runbook.
Still stuck? Contact the node administrator.