Deployment with Docker Compose
This guide walks you through deploying MicroPowerManager using Docker Compose on a standalone Linux server. This approach is ideal for production deployments where you need full control over your infrastructure.
INFO
For production deployments, additional configuration steps are required including:
- Installing a web server like Nginx as a reverse proxy
- Managing TLS certificates with Let's Encrypt
- General Linux server maintenance (system updates, security patches, performance monitoring)
There are plenty of great resources available online that cover these topics in detail.
Prerequisites
Before you begin, ensure your server meets the following requirements.
Server Access
- SSH access to the server
- A user with
sudoprivileges, required for installing Docker, Nginx and configuring the firewall
All commands in this guide are run on the server over SSH.
System Requirements
- Operating System: 64-bit Linux, for example Ubuntu 24.04 LTS or Debian 12
- CPU Architecture:
x86_64(amd64) orarm64 - RAM: Minimum 4GB, 8GB recommended for production
- Storage: 20GB free disk space minimum
- CPU: 2 cores minimum, 4 cores recommended for production
- Network: Outbound internet access to pull images from Docker Hub
WARNING
macOS and Windows (including WSL2) are not supported as server operating systems. MicroPowerManager images are only published for linux/amd64 and linux/arm64. To try MicroPowerManager on a laptop, follow the Development Environment guide instead.
Software Requirements
- Docker Engine: Version 24 or higher, installed following the official instructions for your distribution. Docker Desktop is not required and not recommended on servers.
- Docker Compose plugin: Version 2 or higher (
docker compose, not the legacydocker-compose) - Git: For cloning the repository (optional)
Verify Prerequisites
Check your Docker installation:
docker --version
docker compose versionBoth commands should return version information without errors.
1. Create Project Directory
Create a dedicated directory for your MicroPowerManager deployment:
mkdir micro-powermanager
cd micro-powermanager2. Environment Configuration
Create three .env files to separate configuration for backend, frontend, and MySQL.
# From your micro-powermanager directory
touch .env.backend .env.frontend .env.mysqlAdd the following configuration to each file, updating values for your environment. DB_PASSWORD in .env.backend must match MYSQL_ROOT_PASSWORD in .env.mysql.
# Application Configuration
APP_ENV=production
APP_KEY=base64:your-generated-app-key-here
APP_DEBUG=false
APP_URL=https://api.your-domain.com
MPM_FRONTEND_URL=https://your-domain.com
JWT_SECRET=your-generated-jwt-secret-here
# Database Configuration (host is the "mysql" service from compose)
DB_CONNECTION=micro_power_manager
DB_HOST=mysql
DB_PORT=3306
DB_DATABASE=micro_power_manager
DB_USERNAME=root
DB_PASSWORD=your-secure-database-password
# Cache Configuration
CACHE_DRIVER=redis
REDIS_HOST=redis
REDIS_PORT=6379
# MicroPowerManager Configuration
MPM_LOAD_DEMO_DATA=false
MPM_ENV=productionMPM_ENV=production
MPM_BACKEND_URL=https://api.your-domain.comMYSQL_ROOT_PASSWORD=your-secure-database-password
MYSQL_DATABASE=micro_power_managerSee Environment Variables for the full list of supported settings.
3. Generate Secrets
Generate the Laravel application key:
openssl rand -base64 32Paste the output into APP_KEY in .env.backend, keeping the base64: prefix.
Generate the JWT secret:
openssl rand -base64 48Paste the output into JWT_SECRET in .env.backend.
4. Create Docker Compose File
Create a docker-compose.yml file with the following configuration:
services:
backend:
image: enaccess/micropowermanager-backend:latest
env_file:
- .env.backend
ports:
# Only reachable from the server itself, expose it via the reverse proxy
- 127.0.0.1:8000:80
depends_on:
mysql:
condition: service_healthy
redis:
condition: service_started
restart: unless-stopped
volumes:
- storage_data:/var/www/html/storage
healthcheck:
test: [CMD, curl, -f, http://localhost/up]
start_period: 60s
interval: 30s
timeout: 10s
retries: 3
frontend:
image: enaccess/micropowermanager-frontend:latest
env_file:
- .env.frontend
ports:
# Only reachable from the server itself, expose it via the reverse proxy
- 127.0.0.1:8001:80
depends_on:
- backend
restart: unless-stopped
scheduler:
image: enaccess/micropowermanager-scheduler:latest
env_file:
- .env.backend
depends_on:
mysql:
condition: service_healthy
redis:
condition: service_started
restart: unless-stopped
volumes:
- storage_data:/var/www/html/storage
worker:
image: enaccess/micropowermanager-queue-worker:latest
env_file:
- .env.backend
depends_on:
mysql:
condition: service_healthy
redis:
condition: service_started
restart: unless-stopped
volumes:
- storage_data:/var/www/html/storage
healthcheck:
test:
[
CMD,
php,
/var/www/html/artisan,
mpm-system-checks:horizon,
--local,
--quiet,
]
start_period: 60s
interval: 30s
timeout: 10s
retries: 5
mysql:
image: mysql:8.4
env_file:
- .env.mysql
restart: unless-stopped
volumes:
- mysql_data:/var/lib/mysql
healthcheck:
test: [CMD, mysqladmin, ping, -h, localhost]
start_period: 10s
interval: 10s
timeout: 5s
retries: 3
redis:
image: redis:7
restart: unless-stopped
volumes:
- redis_data:/data
volumes:
mysql_data:
redis_data:
storage_data:MySQL and Redis are intentionally not published on the host. The other services reach them over the internal Compose network.
WARNING
Ports published by Docker bypass host firewalls such as ufw. Never publish MySQL or Redis ports, and bind the backend and frontend to 127.0.0.1 as shown above.
5. Deploy MicroPowerManager
Start all services:
docker compose up -dThis command will:
- Download the required Docker images
- Create and start all containers
- Set up networking between services
- Create persistent volumes for data storage
On first start, the backend runs all database migrations before it becomes healthy.
6. Verify Deployment
Check that all services are running and healthy:
# Check service status
docker compose ps
# View logs if needed
docker compose logs -fTest the backend health endpoint:
curl -fsS -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8000/upExpected response: 200
7. Access Your Application
At this point MicroPowerManager is only reachable from the server itself:
- Frontend: http://127.0.0.1:8001
- Backend API: http://127.0.0.1:8000
Continue with Production Configuration to expose it on your domain.
WARNING
The application is not yet fully configured for production use. You'll need to complete additional setup steps including the reverse proxy, TLS certificates, user creation and company configuration.
Alternative: Quick Start with Provided Compose Files
WARNING
This approach is provided for quick testing and development. It uses the development configuration from dev/ and publishes MySQL and Redis on the host. For production deployments, use the Custom Docker Compose Setup above.
If you want to get started quickly without customizing the configuration, you can use the provided compose files as a starting point.
Option 1: DockerHub Images
# Clone the repository
git clone https://github.com/EnAccess/micropowermanager.git
cd micropowermanager
# Start all services
docker compose -f docker-compose-dockerhub.yml up -dOption 2: Build Locally
# Clone the repository
git clone https://github.com/EnAccess/micropowermanager.git
cd micropowermanager
# Start all services
docker compose -f docker-compose-prod.yml up -dService Management
Start Services
# Start all services
docker compose up -d
# Start specific service
docker compose up -d backendStop Services
# Stop all services
docker compose stop
# Stop specific service
docker compose stop backendView Logs
# View all logs
docker compose logs -f
# View specific service logs
docker compose logs -f backend
# View last 100 lines
docker compose logs --tail=100 backendRestart Services
# Restart all services
docker compose restart
# Restart specific service
docker compose restart backendUpdate to a New Release
docker compose pull
docker compose up -dTroubleshooting
Common Issues
Services Won't Start
Check Docker is running:
bashdocker --version docker compose versionCheck port conflicts:
bash# Check if ports are in use sudo ss -tulpn | grep -E ':(8000|8001)\b'Check logs for errors:
bashdocker compose logs backend docker compose logs mysql
Database Connection Issues
Verify MySQL is running:
bashdocker compose ps mysqlCheck database logs:
bashdocker compose logs mysqlTest database connection:
bashdocker compose exec mysql mysql -u root -pCheck the passwords match:
DB_PASSWORDin.env.backendmust equalMYSQL_ROOT_PASSWORDin.env.mysql.MYSQL_ROOT_PASSWORDis only applied when themysql_datavolume is first created.
Backend Health Check Fails
Check backend logs:
bashdocker compose logs backendVerify environment variables:
bashdocker compose exec backend env | grep DB_Test internal connectivity:
bashdocker compose exec backend curl http://localhost/up
Service Ports
| Service | Port | Reachable from | Description |
|---|---|---|---|
| Backend | 8000 | Server only (local) | HTTP API |
| Frontend | 8001 | Server only (local) | Web Interface |
| MySQL | 3306 | Compose network | Database |
| Redis | 6379 | Compose network | Cache |
Data Persistence
The following data is persisted using Docker volumes:
- mysql_data: Database files
- redis_data: Cache data
- storage_data: Application files and uploads
To backup your data:
# Backup database
docker compose exec mysql mysqldump -u root -p micro_power_manager > backup.sql
# Backup application storage
docker run --rm -v micro-powermanager_storage_data:/data -v $(pwd):/backup alpine tar czf /backup/storage_backup.tar.gz /dataProduction Configuration
For production deployment, you'll need to configure the following.
DNS Configuration
Point your domains to your server's IP address:
| Record Type | Name | Value |
|---|---|---|
| A | your-domain.com | your-server-ip |
| A | api.your-domain.com | your-server-ip |
Web Server Setup
Install Nginx as a reverse proxy, serving the frontend and backend on separate domains to match APP_URL, MPM_FRONTEND_URL and MPM_BACKEND_URL:
sudo apt install nginxCreate /etc/nginx/sites-available/micropowermanager:
server {
listen 80;
server_name your-domain.com;
location / {
proxy_pass http://127.0.0.1:8001;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
server {
listen 80;
server_name api.your-domain.com;
location / {
proxy_pass http://127.0.0.1:8000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}Enable the site:
sudo ln -s /etc/nginx/sites-available/micropowermanager /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginxConfigure the backend to trust the proxy headers, see Configuring Trusted Proxies.
SSL Certificate Setup
Use Let's Encrypt for free SSL certificates:
# Install Certbot
sudo apt install certbot python3-certbot-nginx
# Obtain certificates for both domains
sudo certbot --nginx -d your-domain.com -d api.your-domain.comFirewall Configuration
Configure the firewall to allow only SSH, HTTP and HTTPS:
sudo ufw allow 22
sudo ufw allow 80
sudo ufw allow 443
sudo ufw enableNext Steps
After successful deployment, your MicroPowerManager instance will be accessible at your configured domain. However, additional configuration is required for production use:
- User Management: Create admin users and configure authentication
- Company Setup: Configure your company information and settings
- Security: Review and implement security best practices
- Monitoring: Set up monitoring and alerting
- Backups: Implement regular backup procedures
Please proceed to Configuration for Production to complete your setup.
