Installation Guide

Step-by-step guide to installing and setting up DeepChain

Installation Guide

Get DeepChain up and running in minutes. We'll walk you through everything, whether you're developing locally or deploying to production.

Recommended: Start with Docker (it's the easiest). Jump to Cloud Deployments if you're deploying to AWS, GCP, or Azure.

Prerequisites Checklist

Before you start, make sure you have:

  • Docker 20.10+ — Install Docker
  • Docker Compose 2.0+ — Usually comes with Docker Desktop
  • Git — Install Git
  • 4GB RAM minimum (8GB recommended) on your machine

Note: That's it for local development. No need to install Dart, Flutter, or anything else unless you're customizing DeepChain's code.

Option 1: Docker (Recommended)

The fastest way to get started. Everything runs in Docker containers.

Step 1: Clone the Repository

git clone https://github.com/aice-technology/deepchain.git
cd deepchain

Step 2: Initialize DeepChain

./deepchain init

This creates a .env file with sensible defaults and generates configuration files.

Step 3: Start All Services

./deepchain deploy

Docker Compose will now spin up all services. You'll see output like:

Creating deepchain_postgres_1 ... done
Creating deepchain_rabbitmq_1 ... done
Creating deepchain_redis_1 ... done
Creating deepchain_api_server_1 ... done
Creating deepchain_workflow_runner_1 ... done
Creating deepchain_frontend_1 ... done

Step 4: Verify Everything Is Running

./deepchain status

Expected output:

Service              Status      Port
────────────────────────────────────
frontend             running     3000
api_server           running     8080
workflow_runner      running     (background)
postgres             running     5432
rabbitmq             running     5672
redis                running     6379

Step 5: Open DeepChain

Open your browser and navigate to:

http://localhost:3000

You should see the DeepChain dashboard. Congratulations! DeepChain is running.

What's Running

Here's what each service does:

Service Purpose Port
Frontend Web UI (React/Flutter) 3000
API Server REST API and authentication 8080
Workflow Runner Executes workflows in background (internal)
PostgreSQL Stores workflows and data 5432
RabbitMQ Message queue for jobs 5672
Redis Cache and sessions 6379

All services are pre-configured to work together. No manual setup needed.

Option 2: Development Setup

Use this if you're contributing to DeepChain or building custom nodes.

Prerequisites

  • Dart SDK 3.0+
  • Flutter SDK 3.8+
  • Node.js 18+
  • PostgreSQL 14+
  • RabbitMQ 3.12+
  • Redis 6+

Setup Steps

# Clone the repository
git clone https://github.com/aice-technology/deepchain.git
cd deepchain

# Install dependencies and generate code
./deepchain dev setup

# Run tests to verify setup
./deepchain test

Run Services with Hot Reload

In separate terminal windows:

# Terminal 1: API Server (auto-reloads on code changes)
cd api_server
dart_frog dev
# Terminal 2: Workflow Runner
cd workflow_runner
dart run bin/main.dart
# Terminal 3: Frontend (auto-reloads on code changes)
cd frontend
flutter run -d chrome

Tip: Hot reload means your code changes show up instantly without restarting services.

Configuration

Environment Variables

When you run ./deepchain init, it creates a .env file. Here are the important ones:

# Database connection
DATABASE_URL=postgresql://deepchain:password@localhost:5432/deepchain

# Message queue
RABBITMQ_URL=amqp://guest:guest@localhost:5672

# Cache
REDIS_URL=redis://localhost:6379

# Security (generate a random 32+ character string)
JWT_SECRET=your-secret-key-here-min-32-characters

# AI API Keys (optional, add only if you use AI nodes)
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_AI_API_KEY=...

# Email notifications (optional)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password

Loading Custom Configuration

If you need to change ports or add API keys:

# Edit the .env file
nano .env

# Restart services
./deepchain teardown
./deepchain deploy

Verify Installation

Health Check (Quick)

./deepchain status

Detailed Health Check

# Check API server
curl http://localhost:8080/health

# Check frontend
curl http://localhost:3000/health

Access Management Consoles

While services are running, you can access:

Troubleshooting

Services Won't Start

# Run diagnostics
./deepchain diagnose

# Check logs
./deepchain logs

# Clean up and restart
./deepchain teardown
./deepchain deploy

Database Connection Error

# Check if postgres is running
./deepchain status

# Access the database shell
./deepchain db shell

# Run migrations
./deepchain migrate

Port Already in Use

# Find what's using port 3000
lsof -i :3000

# Or change the port in .env
nano .env
# Change: FRONTEND_PORT=3001
./deepchain deploy

API Server Not Responding

# Check API server logs
./deepchain logs api_server

# Restart just the API server
./deepchain restart api_server

Cloud Deployments

Ready to deploy beyond your laptop? We support all major cloud providers.

AWS (ECS or Lambda)

cd deployments/aws/self-hosted
terraform init
terraform plan
terraform apply

See the AWS Deployment Guide for details.

Google Cloud Platform (Cloud Run)

cd deployments/gcp/self-hosted
./deploy.sh --project your-project-id

See the GCP Deployment Guide for details.

Azure (Container Instances or AKS)

cd deployments/azure/self-hosted
az deployment group create \
  --resource-group deepchain-rg \
  --template-file main.bicep

See the Azure Deployment Guide for details.

Database Setup (Optional)

If you want to seed demo data:

# Run migrations
./deepchain migrate

# Load demo workflows and credentials
./deepchain seed

This creates sample workflows and test data so you can explore without building from scratch.

Next Steps

Your DeepChain instance is now running. What's next?

Quick Start Tutorial → — Build your first workflow in 5 minutes.

Core Concepts → — Understand workflows, nodes, and expressions.

50+ Built-in Nodes → — Explore what's available.