Managing Projects

Learn how to manage the lifecycle of your Supabase projects - starting, stopping, monitoring, and deleting.

Project States

Start a Project

Via Web UI

1. Navigate to Projects
2. Find the stopped project
3. Click the Start button
4. Monitor progress in real-time

Via API

curl -X POST https://supascale.example.com/api/v1/projects/my-project/start \
  -H "X-API-Key: your-api-key"

Returns Server-Sent Events with startup progress.

Stop a Project

Via Web UI

1. Navigate to Projects
2. Find the running project
3. Click the Stop button
4. Wait for confirmation

Via API

curl -X POST https://supascale.example.com/api/v1/projects/my-project/stop \
  -H "X-API-Key: your-api-key"

Graceful shutdown preserves all data.

Restart a Project

Restart applies configuration changes and refreshes containers:

Via Web UI

1. Navigate to Projects
2. Click project menu (...)
3. Select Restart

Via API

# Stop then start
curl -X POST https://supascale.example.com/api/v1/projects/my-project/stop \
  -H "X-API-Key: your-api-key"

curl -X POST https://supascale.example.com/api/v1/projects/my-project/start \
  -H "X-API-Key: your-api-key"

Check Project Status

Via Web UI

Project cards show current status with color indicators:

• 🟢 Green: Running
• 🔴 Red: Stopped or Error
• 🟡 Yellow: Starting/Stopping

Via API

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

Response:

{
  "status": "running",
  "lastChecked": "2026-01-19T12:00:00Z",
  "containers": {
    "total": 8,
    "running": 8,
    "stopped": 0
  }
}

View Containers

See individual container status:

Via Web UI

1. Click on a project
2. Go to Containers tab
3. View status, uptime, and resource usage

Via API

# Without stats
curl https://supascale.example.com/api/v1/projects/my-project/containers \
  -H "X-API-Key: your-api-key"

# With CPU/memory stats
curl "https://supascale.example.com/api/v1/projects/my-project/containers?stats=true" \
  -H "X-API-Key: your-api-key"

Response:

{
  "containers": [
    {
      "name": "my-project-db",
      "service": "db",
      "status": "running",
      "state": "Up 2 hours",
      "stats": {
        "cpu": "2.5%",
        "memory": "256MB / 1GB"
      }
    }
  ]
}

View Logs

Access container logs for debugging:

Via Web UI

1. Click on a project
2. Go to Logs tab
3. Filter by service or search

Via API

# All logs
curl "https://supascale.example.com/api/v1/projects/my-project/logs?tail=100" \
  -H "X-API-Key: your-api-key"

# Specific service
curl "https://supascale.example.com/api/v1/projects/my-project/logs?service=db&tail=50" \
  -H "X-API-Key: your-api-key"

Response:

{
  "logs": [
    {
      "timestamp": "2026-01-19T12:00:00Z",
      "service": "db",
      "level": "info",
      "message": "database system is ready to accept connections"
    }
  ]
}

Delete a Project

Deleting a project removes all containers. Optionally removes all data files.

Via Web UI

1. Navigate to Projects
2. Click project menu (...)
3. Select Delete
4. Choose whether to remove files
5. Confirm deletion

Via API

# Keep files
curl -X DELETE https://supascale.example.com/api/v1/projects/my-project \
  -H "X-API-Key: your-api-key"

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

Bulk Operations

Manage multiple projects at once:

Stop All Projects

# Get all project IDs
projects=$(curl -s https://supascale.example.com/api/v1/projects \
  -H "X-API-Key: your-api-key" | jq -r '.[].id')

# Stop each
for project in $projects; do
  curl -X POST "https://supascale.example.com/api/v1/projects/$project/stop" \
    -H "X-API-Key: your-api-key"
done

Resource Management

View Resource Usage

Monitor project resource consumption:

1. Go to Resources
2. View per-project breakdown
3. Identify resource-heavy projects

Optimize Resources

1. Stop unused projects - Don't run what you don't need
2. Disable unused services - Reduce container count
3. Monitor memory - Watch for memory leaks
4. Clean old images - docker image prune

Troubleshooting

Project Won't Start

1. Check Docker daemon: systemctl status docker
2. Verify resources: free -m, df -h
3. Check port conflicts: netstat -tlnp | grep <port>
4. Review logs: pm2 logs supascale-web

Project Shows Error State

1. Check container logs for errors
2. Verify all required images exist
3. Check disk space for volumes
4. Try stopping and starting again

Containers Keep Restarting

1. Check container health logs
2. Verify environment variables
3. Check memory limits
4. Review application logs