skywatch/DOCKER.md

Docker Setup for SkyWatch

This guide explains how to build and run SkyWatch using Docker.

Prerequisites

• Docker and Docker Compose installed on your system
• A .env file configured in the project root (see README.md for configuration details)

Building Locally

Using Docker Compose (Recommended)

The easiest way to build and run SkyWatch with Docker:

docker-compose up -d

This will:

1. Build the Docker image
2. Create a container named skywatch-monitor
3. Start the application on port 3001
4. Mount a persistent volume for data storage

Using Docker Directly

To build the image manually:

docker build -t skywatch:latest .

To run the container:

docker run -d \
  --name skywatch \
  -p 3001:3001 \
  --env-file .env \
  -v skywatch-data:/app/data \
  skywatch:latest

Pushing to GitHub Container Registry (GHCR)

Automatic Deployment (Recommended)

The project includes a GitHub Actions workflow (.github/workflows/docker-publish.yml) that automatically:

• Builds your Docker image when you push to main or create a tag
• Pushes it to GitHub Container Registry (GHCR)
• Tags images as:
  • latest (for main branch)
  • Branch name (e.g., main)
  • Semantic version (if you push a tag like v1.0.0)
  • Short commit SHA

No configuration needed! The workflow uses GitHub's built-in authentication.

Manual Push to GHCR

If you want to push manually:

1. Authenticate with GitHub Container Registry:

echo ${{ secrets.GITHUB_TOKEN }} | docker login ghcr.io -u USERNAME --password-stdin
# Or use a Personal Access Token (PAT) with `read:packages` and `write:packages` scopes

2. Build and tag the image:

docker build -t ghcr.io/YOUR-USERNAME/monitor:latest .

3. Push to GHCR:

docker push ghcr.io/YOUR-USERNAME/monitor:latest

Viewing Published Images

Visit: https://github.com/nmemmert/monitor/pkgs/container/monitor

Or pull the image:

docker pull ghcr.io/nmemmert/monitor:latest

Managing Containers

View running containers

docker ps

View logs

docker logs skywatch-monitor
# Follow logs in real-time
docker logs -f skywatch-monitor

Stop the container

docker-compose down
# Or
docker stop skywatch-monitor

Remove containers and volumes

docker-compose down -v

Environment Variables

Make sure your .env file is in the project root with required variables:

PORT=3001
NODE_ENV=production
# Add other environment variables as needed

The .env file is loaded by Docker Compose from the env_file directive.

Health Checks

The Docker container includes a health check that verifies the API is responding:

docker inspect skywatch-monitor --format='{{.State.Health.Status}}'

Troubleshooting

Container exits immediately

Check logs:

docker logs skywatch-monitor

Port already in use

Change the port in docker-compose.yml:

ports:
  - "3002:3001"  # Access at localhost:3002

Database issues

Clear the volume and rebuild:

docker-compose down -v
docker-compose up -d

Permission issues

The container runs as non-root user (nodejs). Ensure .env file permissions allow reading.

Production Deployment

For production environments, consider:

1. Using a reverse proxy (nginx, traefik)
2. Setting up SSL/TLS certificates
3. Using environment-specific .env files
4. Implementing container orchestration (Kubernetes, Docker Swarm)
5. Setting resource limits in docker-compose.yml:

services:
  skywatch:
    # ... other config
    deploy:
      resources:
        limits:
          cpus: '1'
          memory: 512M
        reservations:
          cpus: '0.5'
          memory: 256M