rConfig V8 Core Docker Deployment

After reading this page, you can deploy rConfig V8 Core in containers using Docker and Docker Compose, run the installation wizard, and sign in to a working instance. It also covers day-to-day operations: backups, updates, troubleshooting, and basic hardening.

When to use this

Use Docker when you want a fast, repeatable rConfig V8 Core install without configuring PHP, a web server, and a database by hand. It suits lab, evaluation, and small-team deployments where everything runs on a single host.

For a traditional package-based install on a dedicated server, follow the V8 Core installation guide instead.

Running a different edition?

This page covers the free, open-source V8 Core edition. For Docker guidance on the Pro, Enterprise, or Vector editions, see the Docker Deployments guide on the Pro docs site, which is a separate edition.

Prerequisites

• Docker Engine 20.10 or later
• Docker Compose 2.0 or later
• Git
• A host with at least 2GB RAM
• Port 8080 available, or an alternative port you can configure

Step-by-step walkthrough

1. Clone the repository

git clone https://github.com/rconfig/rconfig8coredocker.git
cd rconfig8coredocker

2. Configure the environment

Copy the bundled example and edit the values marked [EDIT]:

cp .env.example .env
# then edit .env

At a minimum, review these:

• RCONFIG_VERSION: the prebuilt release to run. Pin it (for example 8.2.7) for production; it falls back to latest.
• APP_URL: the URL users browse to, including the port if it is not 80 or 443.
• DB_PASSWORD and MYSQL_ROOT_PASSWORD: replace the defaults with strong, unique values.
• TIMEZONE: your local timezone.

Where does storage live?

Device config backups, logs, and keys persist in a Docker named volume (storage_data) by default, so they survive upgrades. To keep them on a visible host path instead, switch the app service storage volume to the bind mount option shown in docker-compose.yml. The storage location is set there, not in .env.

Set strong passwords for production

Before any production use, set APP_DEBUG=false and replace the default DB_PASSWORD and MYSQL_ROOT_PASSWORD with strong, unique values.

3. Pull and start the containers

The image is prebuilt and published on Docker Hub, so there is nothing to compile.

# Pull the prebuilt multi-arch image
docker compose pull

# Start all services
docker compose up -d

# Verify status
docker compose ps

4. Run the installation wizard

# Execute installation wizard
docker compose exec app php artisan v8core:install

# When prompted:
# - "Add a cron entry for task scheduling?" -> yes

5. Access the application

Open http://localhost:8080 in your browser and sign in with the default credentials:

• Username: admin@domain.com
• Password: admin

Change the default credentials

Change the default username and password immediately after your first login. Anyone who can reach the instance can sign in with the published defaults.

Common gotchas

Common gotchas

• The database container needs time to initialise on first startup. If the app reports a database connection error right after docker compose up, wait 30 seconds and restart the app container before assuming a misconfiguration.
• SSL/TLS is not enabled by default. Do not expose an HTTP-only instance to the internet. Configure HTTPS first, see SSL configuration in rConfig V8 Core.
• Leaving the default passwords and admin@domain.com / admin credentials in place is the most common security mistake. Change both the application login and the database passwords before going live.
• Port 8080 is often already in use. If a container fails to start, check for a port conflict with netstat -tulpn | grep 8080 and change the published port in docker-compose.yml.

Post-installation checks

Verify services

# Check all services running
docker compose exec app supervisorctl status

# Expected output:
# apache2          RUNNING
# horizon          RUNNING
# redis-server     RUNNING
# schedule-run_00  RUNNING

Access the Horizon dashboard

Monitor queues at http://localhost:8080/horizon. For more on queue processing, see the Horizon queue manager.

Fix mail configuration errors (if needed)

For testing and development environments, route mail to the log driver:

docker compose exec app bash -c "cat >> /var/www/html/rconfig/.env << 'EOF'
MAIL_MAILER=log
MAIL_FROM_ADDRESS=noreply@rconfig.local
MAIL_FROM_NAME=rConfig
EOF"

docker compose exec app php artisan config:clear
docker compose restart app

Common operations

View logs

# Application logs
docker compose logs -f app

# Laravel logs
docker compose exec app tail -f /var/www/html/rconfig/storage/logs/laravel.log

Execute Artisan commands

docker compose exec app php artisan [command]

# Examples:
docker compose exec app php artisan config:clear
docker compose exec app php artisan cache:clear
docker compose exec app php artisan horizon:status

Restart services

# Restart all containers
docker compose restart

# Restart specific service
docker compose exec app supervisorctl restart horizon

Database management

Back up the database

# Create backup with timestamp
docker compose exec -T db mysqldump -u root -proot_password rconfig > rconfig-backup-$(date +%Y%m%d-%H%M%S).sql

Automate backups

Schedule a nightly dump with cron:

# crontab -e
0 2 * * * cd /path/to/rconfig8coredocker && docker compose exec -T db mysqldump -u root -proot_password rconfig > backups/rconfig-$(date +\%Y\%m\%d).sql

Restore the database

docker compose stop app
docker compose exec -T db mysql -u root -proot_password rconfig < rconfig-backup-20251222.sql
docker compose start app
docker compose exec app php artisan config:clear

Access the database

docker compose exec db mysql -u root -proot_password rconfig

Updates

Automated update

chmod +x update.sh
./update.sh

The script handles backup, pull, and migrate in sequence.

Manual update

# Backup
docker compose exec -T db mysqldump -u root -proot_password rconfig > backup.sql

# Set RCONFIG_VERSION in .env to the release you want, then pull the new image
docker compose pull
docker compose up -d

# Apply migrations. Caches are rebuilt automatically on container start.
docker compose exec app php artisan migrate --force
docker compose exec app php artisan horizon:terminate

Update to a specific version

Set RCONFIG_VERSION in .env to the release you want, then pull:

# .env: RCONFIG_VERSION=8.2.7
docker compose pull
docker compose up -d
docker compose exec app php artisan migrate --force

Upgrading from a build-based install?

Earlier versions of the kit built the image locally (docker compose build). Switching to the prebuilt image keeps all your data, because the volume names are unchanged: pull the latest kit, add RCONFIG_VERSION to your existing .env, then docker compose pull && docker compose up -d && docker compose exec app php artisan migrate --force. The old locally built image and the now-unused bootstrap_cache volume can be pruned afterwards.

Troubleshooting

Container won’t start

# Check logs
docker compose logs app

# Check port conflicts
netstat -tulpn | grep 8080

# Fix permissions
docker compose exec app chown -R www-data:www-data /var/www/html/rconfig/storage
docker compose exec app chmod -R 775 /var/www/html/rconfig/storage

Database connection errors

# Check database health
docker compose ps db

# Wait for initialization (first startup)
sleep 30 && docker compose restart app

# Recreate database
docker compose down
docker compose up -d db
sleep 30
docker compose up -d app

Permission errors (500)

docker compose exec app chown -R www-data:www-data /var/www/html/rconfig/storage /var/www/html/rconfig/bootstrap/cache
docker compose exec app chmod -R 775 /var/www/html/rconfig/storage /var/www/html/rconfig/bootstrap/cache
docker compose exec app php artisan config:clear
docker compose exec app php artisan cache:clear

Horizon not processing

# Check status
docker compose exec app php artisan horizon:status

# Restart
docker compose exec app supervisorctl restart horizon
# OR
docker compose exec app php artisan horizon:terminate

Application slow

# Clear caches
docker compose exec app php artisan optimize:clear

# Optimize
docker compose exec app php artisan optimize

# Restart
docker compose restart app

Security hardening

Change ports

Edit docker-compose.yml:

services:
  app:
    ports:
      - "9443:80" # External port
  db:
    ports:
      - "127.0.0.1:3306:3306" # Localhost only

Firewall rules

# Allow specific IPs only
sudo ufw allow from 10.0.0.0/8 to any port 8080

Secure files

chmod 600 .env
echo ".env" >> .gitignore

For a broader checklist, see security hardening for rConfig V8 Core.

Performance optimization

The container caches config, routes, and views on every start and ships an optimised autoloader, so there is nothing to run by hand. If you change .env and want the caches rebuilt, restart the app container and the entrypoint does it for you:

docker compose restart app

Migration from a traditional install

# 1. Backup existing
mysqldump -u root -p rconfig > migration-backup.sql
tar -czf storage-backup.tar.gz /path/to/rconfig/storage

# 2. Deploy Docker (follow the walkthrough above)

# 3. Restore database
docker compose exec -T db mysql -u root -proot_password rconfig < migration-backup.sql

# 4. Restore storage
tar -xzf storage-backup.tar.gz
docker cp storage/. rconfig_app:/var/www/html/rconfig/storage/
docker compose exec app chown -R www-data:www-data /var/www/html/rconfig/storage

# 5. Clear caches
docker compose exec app php artisan config:clear
docker compose restart app

FAQ

Can I run multiple instances on the same server? Yes. Clone the repository to different directories and change the published ports in each docker-compose.yml.

How do I change the database password after install?

docker compose exec db mysql -u root -proot_password -e "ALTER USER 'rconfig_user'@'%' IDENTIFIED BY 'new_password';"
docker compose exec app sed -i 's/DB_PASSWORD=.*/DB_PASSWORD=new_password/' /var/www/html/rconfig/.env
docker compose exec app php artisan config:clear
docker compose restart app

Can I use an external database? Yes. Remove the db service from docker-compose.yml and update .env with your external database credentials.

How do I enable HTTPS/SSL? Follow SSL configuration in rConfig V8 Core.

Resources

• GitHub: https://github.com/rconfig/rconfig
• Docker repo: https://github.com/rconfig/rconfig8coredocker
• Docs: https://v8coredocs.rconfig.com
• Support: https://github.com/rconfig/rconfig/issues

What’s next

• Explore the V8 Core features roadmap
• Add and manage network devices
• Set up scheduled configuration backups