SmythOS Studio: Open-Source Visual AI Agent Builder and deployable runtime stack from SmythOS. Start with an intuitive drag-and-drop workspace, extend with custom code, and deploy your agents anywhere — local, cloud, or edge — with full governance and control.
Docker Setup Guide for SmythOS Studio
This guide explains how to run SmythOS Studio using Docker, both with the standalone Dockerfile and the complete docker compose setup.
Contents
- Docker Setup Guide for SmythOS Studio
Prerequisites
- Docker: Version 20.10 or newer
- Docker Compose: Version 2.0 or newer (included with Docker Desktop)
- Root/Admin Access: Required for Docker commands
- System Requirements:
- 8GB RAM minimum
- 10GB free disk space
- Ports 80, 443, 5050, 5053, 8080 available
⚠️ Important: All Docker commands in this guide should be run as root user (Linux/macOS) or Administrator (Windows) to avoid permission issues.
Quick Start with Docker Compose (Recommended)
The docker compose setup provides a ready environment with all necessary services.
1. Clone the Repository
git clone https://github.com/SmythOS/smythos-studio.git
cd smythos-studio
2. Environment Setup
Create your environment file:
cp .env.compose.example .env
(Optional) Edit the .env file with your configuration (e.g. changing default passwords, your domains, etc.)
3. Start All Services
Launch the complete SmythOS UI stack:
⚠️ Run as Root/Admin: Ensure you're running as root (Linux/macOS) or Administrator (Windows)
# Start all services in detached mode
docker compose up -d
# View logs (optional)
docker compose logs -f
4. Access the Application
Once all services are healthy:
- Main Application: http://localhost:6060 (or your configured APP_URL)
- Runtime Server: http://dev.agent.oss.smyth.ai:6060 (or your configured RUNTIME_URL)
Docker Compose Architecture
Services Overview
| Service | Purpose | Port | Health Check |
|---|---|---|---|
| traefik | Reverse proxy & SSL termination | 80, 443, 8080 | Built-in |
| mysql | Database server | 3306 (internal) | mysqladmin ping |
| redis | Cache & session store | 6379 (internal) | redis-cli ping |
| smythos | Main application | 5050, 5053 | HTTP health endpoints |
Network Architecture
┌─────────────────┐ ┌──────────────────┐
│ Internet │────│ Traefik │
│ │ │ (Port 80/443) │
└─────────────────┘ └──────────────────┘
│
┌───────────┼───────────┐
│ │ │
┌───────▼────┐ ┌────▼────┐ ┌───▼────┐
│ SmythOS │ │ MySQL │ │ Redis │
│ (5050/5053)│ │ (3306) │ │ (6379) │
└────────────┘ └─────────┘ └────────┘
Volume Management
- mysql_data: Persistent MySQL database storage
- redis_data: Redis persistence and cache
- smythos_data: Application data and user uploads
- traefik_letsencrypt: SSL certificates storage
Standalone Dockerfile Usage
For custom configurations, you can use the Dockerfile directly.
Running the Container
cp .env.example .env
# Run with environment file
docker run -d \
--name smythos-app \
-p 5050:5050 \
-p 5053:5053 \
--env-file .env \
-v smythos_data:/home/node/smythos-data \
smythos/smythos-studio:alpha
Environment Variables
Required Variables
| Variable | Description | Example |
|---|---|---|
DATABASE_URL |
MySQL connection string | mysql://user:pass@host:3306/db |
Production Deployment
Domain & SSL/TLS Configuration
The docker compose setup includes automatic SSL certificate generation via Let's Encrypt:
Configure your domains & tls configuration in
.env:APP_DOMAIN=https://yourdomain.com RUNTIME_DOMAIN=https://runtime.yourdomain.com DEFAULT_AGENT_DOMAIN=dev.yourdomain.com PROD_AGENT_DOMAIN=live.yourdomain.com [email protected] ENABLE_TLS=true- remove the
AGENT_DOMAIN_PORTvariable
- remove the
Ensure DNS records point to your server:
yourdomain.com A YOUR_SERVER_IP runtime.yourdomain.com A YOUR_SERVER_IP *.dev.yourdomain.com A YOUR_SERVER_IP *.live.yourdomain.com A YOUR_SERVER_IPStart with SSL enabled:
docker compose up -d
Security Considerations
- Change default passwords in
.env - Use strong database credentials
- Configure firewall to only allow necessary ports
- Regular updates of Docker images
- Monitor logs for suspicious activity
Troubleshooting
Common Issues
1. Port conflicts:
If you see errors like:
docker: Error response from daemon: driver failed programming external connectivity on endpoint <container_name> (xxxxxxxxxxxxxxx): Bind for 0.0.0.0:80 failed: port is already allocated.
or
docker: Error response from daemon: driver failed programming external connectivity on endpoint <container_name> (xxxxxxxxxxxxxxx): Error starting userland proxy: listen tcp 0.0.0.0:0: bind: cannot assign requested address.
This means a service is already running on port 80 and/or 443. You need to stop that service first.
# Check what's using the ports
netstat -tlnp | grep :80
netstat -tlnp | grep :443
# Stop any service using 80 and/or 443
2. Services not starting:
# Check service status
docker compose ps
# View logs for specific service
docker compose logs mysql
docker compose logs smythos
3. Database connection errors:
# Verify MySQL is healthy
docker compose exec mysql mysqladmin ping -u root -p
# Check database connectivity from app
docker compose exec smythos sh -c "mysql -h mysql -u \$DATABASE_USER -p\$DATABASE_PASSWORD -e 'SELECT 1'"
Maintenance
Updates
# Down the services
docker compose down
# Pull latest images
docker compose pull
# Rebuild and restart services
docker compose up -d
Support
For issues with Docker deployment:
- Check the Troubleshooting section
- Review container logs:
docker compose logs -f - Verify environment configuration in
.env - Ensure all prerequisites are met
For development setup, see CONTRIBUTING.md for the local development environment.