Docker Setup¶

The easiest way to get started - one command and everything is set up!

Why Docker?¶

✅ No Python installation needed - Everything runs in containers
✅ No pipenv setup - Dependencies are pre-installed
✅ PostgreSQL included - Database runs automatically
✅ Consistent environment - Works the same on all machines
✅ One command setup - make docker-setup and you’re done!

Prerequisites¶

Docker Desktop (macOS/Windows) or Docker Engine (Linux)
- Download: https://www.docker.com/products/docker-desktop
Git (to clone the repository)

That’s it! No Python, pipenv, or PostgreSQL installation needed.

Quick Start¶

1. Clone and Setup¶

git clone https://github.com/Agent-Ship/agent-ship.git
cd agent-ship
make docker-setup

The script will:

Check Docker installation
Create .env file from template
Configure database connection for Docker
Build Docker images
Start all services (API + PostgreSQL)
Wait for services to be ready

2. Add API Keys¶

Edit .env and add at least one LLM API key:

nano .env
# or use your preferred editor

Add your keys:

OPENAI_API_KEY=your-actual-key-here
# or
GOOGLE_API_KEY=your-actual-key-here
# or
ANTHROPIC_API_KEY=your-actual-key-here

3. Restart if Needed¶

If you added keys after starting:

make docker-down
make docker-up

4. Access the API¶

Open in your browser:

API Docs: http://localhost:7001/docs
ReDoc: http://localhost:7001/redoc
Health Check: http://localhost:7001/health

Docker Commands¶

Using Make (Recommended)¶

make docker-setup   # One-command setup
make docker-up      # Start containers
make docker-down    # Stop containers
make docker-logs    # View logs (follow mode)
make docker-build   # Rebuild images

Using Docker Compose Directly¶

docker compose up -d          # Start in background
docker compose down           # Stop containers
docker compose logs -f        # View logs
docker compose ps             # View status
docker compose restart        # Restart services
docker compose build          # Rebuild images

Container Details¶

Services¶

agentship (API Service)
- Port: 7001
- Health check: /health
- Auto-restart: Yes
- Hot-reload: Source code is mounted for development
postgres (Database)
- Port: 5433 (exposed on host; container uses 5432 internally)
- Database: ai_agents_session_store
- User: ai_agents_user
- Password: ai_agents_password
- Data persistence: Volume postgres_data

Environment Variables¶

The .env file is automatically loaded. Key variables:

# Required: At least one LLM provider
OPENAI_API_KEY=your-key
GOOGLE_API_KEY=your-key
ANTHROPIC_API_KEY=your-key

# Database (automatically configured for Docker)
AGENT_SESSION_STORE_URI=postgresql://ai_agents_user:ai_agents_password@postgres:5432/ai_agents_session_store

Note: The database connection string uses postgres as the hostname (Docker service name), not localhost.

Troubleshooting¶

Containers won’t start¶

# Check logs
make docker-logs

# Check status
docker compose ps

# Rebuild from scratch
make docker-down
make docker-build
make docker-up

Port already in use¶

If port 7001 or 5433 is already in use, change ports in docker-compose.yml:

ports:
  - "7002:7001"  # Use 7002 instead

Clean slate¶

To start completely fresh:

# Stop and remove everything
make docker-down
docker volume rm agentship_postgres_data  # Remove database data
docker system prune -f                     # Clean up

# Start again
make docker-setup

Next Steps¶

Follow the Quick Start Guide to create your first agent
Read the Installation Guide for local development
Check out Deployment Guide for production