Skip to content

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.

7.8 KB
Raw Blame

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

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:

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:

  1. 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_PORT variable
  2. 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_IP
    
  3. Start 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:

  1. Check the Troubleshooting section
  2. Review container logs: docker compose logs -f
  3. Verify environment configuration in .env
  4. Ensure all prerequisites are met

For development setup, see CONTRIBUTING.md for the local development environment.