Creating Projects

Supascale makes it easy to create fully-configured Supabase projects with a few clicks.

Create via Web UI

1. Navigate to Projects

Click Projects in the sidebar, then click New Project.

2. Enter Project Details

3. Select Services

Choose which Supabase services to enable:

Core Services (Always Enabled)

These run in every project:

• PostgreSQL - The database
• PostgREST - REST API
• GoTrue - Authentication
• Kong - API Gateway
• Meta - Metadata service
• Studio - Web UI

Optional Services

Enable based on your needs:

4. Create Project

Click Create Project to start. Supascale will:

1. Generate Docker Compose configuration
2. Create project directory
3. Generate secure credentials
4. Pull Docker images
5. Start containers
6. Verify health

Create via API

Use the REST API for programmatic project creation:

Standard Create

curl -X POST https://supascale.example.com/api/v1/projects \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "my-project",
    "name": "My Project",
    "description": "Created via API"
  }'

Response:

{
  "success": true,
  "data": {
    "id": "my-project",
    "name": "My Project",
    "directory": "/var/supascale/projects/my-project",
    "ports": {
      "api": 8000,
      "db": 5432,
      "studio": 3001
    },
    "status": "running",
    "createdAt": "2026-01-19T12:00:00Z"
  }
}

Create with Streaming Progress

For real-time progress updates:

curl -X POST https://supascale.example.com/api/v1/projects/create \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "id": "my-project",
    "name": "My Project",
    "services": ["realtime", "storage"]
  }'

Returns Server-Sent Events:

event: progress
data: {"step": 1, "total": 6, "status": "running", "message": "Validating configuration..."}

event: progress
data: {"step": 2, "total": 6, "status": "running", "message": "Generating Docker Compose..."}

event: progress
data: {"step": 3, "total": 6, "status": "running", "message": "Pulling images..."}

event: complete
data: {"project": {...}}

Project Directory Structure

Each project is created with this structure:

/var/supascale/projects/my-project/
├── docker-compose.yml     # Container configuration
├── .env                   # Environment variables
└── volumes/              # Persistent data
    ├── db/               # PostgreSQL data
    ├── storage/          # File storage
    └── functions/        # Edge functions

Generated Credentials

Supascale generates secure credentials for each project:

View credentials in the project details or via API:

curl https://supascale.example.com/api/v1/projects/my-project?credentials=true \
  -H "X-API-Key: your-api-key"

Port Allocation

Supascale automatically assigns ports to avoid conflicts:

Ports are tracked in the database and reused when projects are deleted.

Best Practices

Naming Conventions

• Use descriptive, lowercase IDs: prod-api, staging-app, dev-test
• Use meaningful names for the UI: "Production API", "Staging Application"

Service Selection

• Development: Enable all services for full functionality
• Production: Enable only needed services to reduce resource usage
• Testing: Enable Inbucket for email testing

Resource Planning

Each project consumes approximately:

• 1 GB RAM (varies by services enabled)
• 5 GB disk space (grows with data)
• CPU scales with load

Troubleshooting

Creation Failed

1. Check disk space: df -h
2. Verify Docker is running: docker ps
3. Check Supascale logs: pm2 logs supascale-web
4. Verify port availability

Images Won't Pull

1. Check internet connectivity
2. Verify Docker Hub access
3. Check disk space for images
4. Try manual pull: docker pull supabase/postgres

Containers Won't Start

1. Check port conflicts: netstat -tlnp
2. Review container logs
3. Verify memory availability
4. Check Docker daemon status