Container Startup

Diagnosing and resolving container startup issues for ActionsManager Self-Hosted.

Table of contents
  1. Quick Diagnostics
  2. Container Fails to Start
    1. Port 8080 Already in Use
    2. Missing or Invalid SECRET_KEY
    3. Volume Mount Permission Error
  3. Container Starts but UI is Inaccessible
    1. Checking Service Health
    2. Database Initialization Errors
  4. Environment Variable Issues
    1. Required Environment Variables
    2. Checking Environment Variables in a Running Container
  5. Memory and Disk Issues
  6. Getting More Help
  7. Related Topics

Quick Diagnostics

Run these commands first for any startup issue:

# Check if the container is running
docker ps --filter name=actions-manager

# View recent logs
docker logs actions-manager --tail=100

# Check port availability
curl -I http://localhost:8080

For Docker Compose:

docker compose -f docker-compose.self-hosted.yml ps
docker compose -f docker-compose.self-hosted.yml logs --tail=100

Container Fails to Start

Port 8080 Already in Use

Symptom: Container exits immediately or port binding fails.

Solution:

# Find what is using port 8080
lsof -i :8080
# or
ss -tlnp | grep 8080

# Stop the conflicting service, or run ActionsManager on a different port:
docker run -p 9090:8080 ...  # map host port 9090 to container port 8080

Missing or Invalid SECRET_KEY

Symptom: Container starts but immediately fails with a configuration error.

Solution: Ensure SECRET_KEY is set when running the container:

-e SECRET_KEY=$(openssl rand -hex 32)

Generate a new secret key if needed. Changing SECRET_KEY on a running deployment will invalidate all existing sessions.

Volume Mount Permission Error

Symptom: Container fails with a permissions error when writing to the data volume.

Solution:

# Check the volume
docker volume inspect actions-manager-data

# Remove and recreate the volume (this deletes all data)
docker volume rm actions-manager-data
docker volume create actions-manager-data

Container Starts but UI is Inaccessible

Checking Service Health 

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

# Check frontend is served
curl -I http://localhost:8080

If the backend health check fails, review logs for startup errors:

docker logs actions-manager --tail=200

Database Initialization Errors

Symptom: Logs show database migration or initialization errors.

Solution:

  1. Check if the data volume is mounted correctly
  2. Check disk space: df -h
  3. If the database is corrupted, back up the volume and reinitialize:
# Stop the container
docker stop actions-manager

# Inspect the volume path
docker volume inspect actions-manager-data

# Restart — the application will attempt to reinitialize the database
docker start actions-manager

Environment Variable Issues

Required Environment Variables

Ensure these are set before starting the container:

Variable Required Description
INSTALLATION_MODE Yes Set to self-hosted
SECRET_KEY Yes Random secret for session encryption
REACT_APP_BACKEND_URL Yes URL where the backend is accessible
REACT_APP_FRONTEND_URL Yes URL where the frontend is accessible
REACT_APP_WEBSOCKET_URL Yes WebSocket URL (ws:// prefix)
GITHUB_CLIENT_ID OAuth only GitHub OAuth App client ID
GITHUB_CLIENT_SECRET OAuth only GitHub OAuth App client secret

Checking Environment Variables in a Running Container 

docker exec actions-manager env | grep -E 'INSTALLATION_MODE|REACT_APP|GITHUB_CLIENT'

Memory and Disk Issues 

# Check memory
free -h

# Check disk space
df -h

# Check container resource usage
docker stats actions-manager

ActionsManager requires at least 4 GB RAM. If the container is OOM-killed, increase available memory or add a swap file.

Getting More Help

If you cannot resolve the issue:

  1. Collect logs: docker logs actions-manager > actions-manager.log 2>&1
  2. Review the Common Errors page
  3. Check GitHub Issues for similar reports
  4. Open a new issue with your logs (redact all secrets and tokens before posting)