Docker Deployment

Docker Compose is the recommended way to deploy EasyShell. All services (Server, Web, MySQL, Redis) are fully containerized — pre-built images are automatically published to Docker Hub and GHCR via GitHub Actions.

Prerequisites

• Docker 24.0 or later
• Docker Compose v2 (included with Docker Desktop)
• At least 4 GB RAM for the full stack
• 10 GB free disk space

Verify your installation:

docker --version
docker compose version

Quick Deploy

git clone https://github.com/easyshell-ai/easyshell.git
cd easyshell
cp .env.example .env      # Edit if needed
docker compose up -d

No local build required — pre-built images are pulled automatically from Docker Hub.

Open http://localhost:18880 → login with easyshell / easyshell@changeme.

Service Architecture

docker-compose.yml defines all four services:

Service	Image	Port	Description
easyshell-server	laolupaojiao/easyshell-server:latest	18080	Java Spring Boot backend + built-in Agent binaries
easyshell-web	laolupaojiao/easyshell-web:latest	18880	React frontend (served by Nginx)
easyshell-mysql	mysql:8.0	13306	Database
easyshell-redis	redis:7-alpine	16379	Cache

Service dependencies: web → server → mysql + redis. Docker Compose uses health checks to ensure correct startup order.

Environment Configuration

.env.example contains all configurable options. Copy it to .env and modify:

# MySQL
MYSQL_PASSWORD=18923ce29fdab04e
MYSQL_DATABASE=easyshell
MYSQL_PORT=13306

# Redis
REDIS_PORT=16379

# Server
SERVER_PORT=18080
JAVA_OPTS=-Xms256m -Xmx512m

# Agent connection URL (change to your server's external IP when deploying agents)
# PROVISION_SERVER_URL=http://your-server-ip:18080

# Web
WEB_PORT=18880

# Security (MUST change in production!)
# JWT_SECRET=your-production-jwt-secret-key-must-be-at-least-64-characters-long-change-me
# ENCRYPTION_KEY=your-production-aes256-key!!

# Docker image source (default: Docker Hub; uncomment to use GHCR)
# EASYSHELL_SERVER_IMAGE=ghcr.io/easyshell-ai/easyshell/easyshell-server:latest
# EASYSHELL_WEB_IMAGE=ghcr.io/easyshell-ai/easyshell/easyshell-web:latest

Caution

Never commit .env files to version control. Always change MYSQL_PASSWORD, JWT_SECRET, and ENCRYPTION_KEY for production.

Verify Services

docker compose ps
docker compose logs easyshell-server
docker compose logs easyshell-web

All services should show healthy status within 1–2 minutes.

Development Setup

To build from source (for development and debugging), use the development compose file:

docker compose -f docker-compose.build.yml up -d

This builds images locally using Dockerfile.server and Dockerfile.web instead of pulling pre-built images.

Production Setup

Security Hardening

Required configuration for production deployments:

1. Change all default passwords — MYSQL_PASSWORD, JWT_SECRET, ENCRYPTION_KEY
2. Set PROVISION_SERVER_URL — change to your server’s externally reachable address
3. Restrict port exposure — MySQL (13306) and Redis (16379) ports are for debugging only; restrict via firewall or remove port mappings in production
4. Configure reverse proxy — use Nginx for TLS termination. See Production Deployment

Resource Limits

Recommended resource limits for production:

Service	Memory Limit	CPU Limit
Server	1 GB	2.0
Web	256 MB	0.5
MySQL	1 GB	1.0
Redis	256 MB	0.5

Data Persistence

All data is stored in named Docker volumes:

• easyshell_mysql_data — Database files
• easyshell_redis_data — Redis AOF persistence

Back up these volumes regularly in production. See the backup guide for automated backup scripts.

Upgrading

To upgrade EasyShell to a new version:

docker compose pull
docker compose up -d

The server handles database migrations automatically on startup.

Tip

Always back up your database before upgrading. Run docker compose exec easyshell-mysql mysqldump -u root -p easyshell > backup.sql before pulling new images.