Docker Deployment

This guide covers deploying gitlab-summary using Docker and docker-compose.

Quick Start

Using docker-compose (Recommended)

Create .env file:

  cat > .env << EOF
GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx
GITLAB_URL=https://gitlab.example.com
GITLAB_GROUP=your-group-id
GITLAB_SINCE=24h
GITLAB_PORT=5100
GITLAB_INTERVAL=30
GH_TOKEN=github_pat_your_token_here
COPILOT_MODEL=claude-sonnet-4-5
EOF

Create docker-compose.yml:

  services:
  gitlab-summary:
    image: garrardkitchen/gitlab-summary:latest
    container_name: gitlab-summary
    ports:
      - "5100:5100"
    environment:
      - GITLAB_GROUP=${GITLAB_GROUP}
      - GITLAB_URL=${GITLAB_URL}
      - GITLAB_TOKEN=${GITLAB_TOKEN}
      - GITLAB_SINCE=${GITLAB_SINCE:-24h}
      - GITLAB_PORT=${GITLAB_PORT:-5100}
      - GITLAB_INTERVAL=${GITLAB_INTERVAL:-30}
      - GH_TOKEN=${GH_TOKEN:-}
      - COPILOT_MODEL=${COPILOT_MODEL:-claude-sonnet-4-5}
    volumes:
      - gitlab-summary-data:/home/ubuntu/.local/share/gitlab-summary
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:5100/api/version"]
      interval: 30s
      timeout: 3s
      retries: 3
      start_period: 10s

volumes:
  gitlab-summary-data:
    driver: local

Start the service:

  docker-compose up -d

Access the dashboard:

Open http://localhost:5100 in your browser.

Using docker run

Linux/Windows - Named Volume

Docker manages the storage location:

  docker run -d \
  --name gitlab-summary \
  -p 5100:5100 \
  -e GITLAB_TOKEN="glpat-xxxxxxxxxxxxxxxxxxxx" \
  -e GITLAB_URL="https://gitlab.example.com" \
  -e GITLAB_GROUP="your-group-id" \
  -e GITLAB_SINCE="24h" \
  -e GITLAB_PORT="5100" \
  -e GITLAB_INTERVAL="30" \
  -e GH_TOKEN="github_pat_your_token_here" \
  -e COPILOT_MODEL="claude-sonnet-4-5" \
  -v gitlab-summary-data:/home/ubuntu/.local/share/gitlab-summary \
  --restart unless-stopped \
  garrardkitchen/gitlab-summary:latest

macOS - Bind Mount

Store data in a specific directory:

  docker run -d \
  --name gitlab-summary \
  -p 5100:5100 \
  -e GITLAB_TOKEN="glpat-xxxxxxxxxxxxxxxxxxxx" \
  -e GITLAB_URL="https://gitlab.example.com" \
  -e GITLAB_GROUP="your-group-id" \
  -e GITLAB_SINCE="24h" \
  -e GITLAB_PORT="5100" \
  -e GITLAB_INTERVAL="30" \
  -e GH_TOKEN="github_pat_your_token_here" \
  -e COPILOT_MODEL="claude-sonnet-4-5" \
  -v ~/.gitlab-summary:/home/ubuntu/.local/share/gitlab-summary \
  --restart unless-stopped \
  garrardkitchen/gitlab-summary:latest

Access the dashboard at: http://localhost:5100

Environment Variables

Variable	Description	Default	Required
`GITLAB_GROUP`	GitLab group ID or path	-	✅ Yes
`GITLAB_URL`	GitLab instance URL	-	✅ Yes
`GITLAB_TOKEN`	GitLab Personal Access Token (`read_api` scope)	-	✅ Yes
`GITLAB_SINCE`	Time range (e.g., `1h`, `24h`, `2d`, `7d`)	`24h`	No
`GITLAB_PORT`	Server port	`5100`	No
`GITLAB_INTERVAL`	Refresh interval in seconds	`30`	No
`GH_TOKEN`	GitHub Fine-grained PAT for Copilot AI	-	No*

* Required only for AI-powered failure analysis. Must have active GitHub Copilot subscription.

Token Setup

GitLab Token

Go to GitLab → Settings → Access Tokens
Create new token with:
- Name: gitlab-summary
- Scopes: read_api ✅
- Expiration: Set as needed
Copy the token (format: glpat-xxxxxxxxxxxxxxxxxxxx)

GitHub Token (Optional - for AI Analysis)

Go to https://github.com/settings/tokens?type=beta
Click “Generate new token”
Configure:
- Token name: gitlab-summary-copilot
- Expiration: 90 days (recommended)
- Account permissions → User permissions:
  - Copilot Chat: Read ✅
  - User copilot requests: Read ✅
  - Gists: Read and Write ✅
Copy the token (format: github_pat_xxxxxxxxxxxxxxxxxxxx)

Note: You must have an active GitHub Copilot subscription.

Managing the Container

View Logs

  # Follow logs in real-time
docker-compose logs -f

# View last 50 lines
docker-compose logs --tail=50

# View logs for specific service
docker logs gitlab-summary

Stop/Start/Restart

  # Stop
docker-compose down

# Start
docker-compose up -d

# Restart
docker-compose restart

# Rebuild and restart (after pulling new image)
docker-compose pull
docker-compose up -d

Check Status

  # Check if container is running
docker-compose ps

# Check health status
docker ps --filter name=gitlab-summary

# Test health endpoint
curl http://localhost:5100/api/version

Update to Latest Version

  # Pull latest image
docker-compose pull

# Restart with new image
docker-compose up -d

# Verify version
curl http://localhost:5100/api/version

Data Persistence

GitLab token data is stored in a Docker volume:

  # List volumes
docker volume ls

# Inspect volume
docker volume inspect gitlab-summary_gitlab-summary-data

# Backup volume (Linux/macOS)
docker run --rm \
  -v gitlab-summary_gitlab-summary-data:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/gitlab-summary-backup.tar.gz -C /data .

# Restore volume
docker run --rm \
  -v gitlab-summary_gitlab-summary-data:/data \
  -v $(pwd):/backup \
  alpine tar xzf /backup/gitlab-summary-backup.tar.gz -C /data

Networking

Custom Port

Change the port mapping in docker-compose.yml or with -p:

  ports:
  - "8080:5100"  # Access on port 8080

Or with docker run:

  docker run -d -p 8080:5100 ...

Access at: http://localhost:8080

Reverse Proxy

Example nginx configuration:

  server {
    listen 80;
    server_name gitlab-summary.example.com;

    location / {
        proxy_pass http://localhost:5100;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

Troubleshooting

Container Won’t Start

Check logs:

  docker-compose logs

Common issues:

Missing required environment variables (GITLAB_TOKEN, GITLAB_URL, GITLAB_GROUP)
Invalid GitLab token or expired token
Port 5100 already in use

Dashboard Not Accessible

Check if container is running:

  docker ps --filter name=gitlab-summary

Test health endpoint:

  curl http://localhost:5100/api/version

Check port binding:

  docker port gitlab-summary
# Should show: 5100/tcp -> 0.0.0.0:5100

AI Analysis Not Working

Check GitHub token:

  docker exec gitlab-summary env | grep GH_TOKEN

Common issues:

GH_TOKEN not set or incorrect format
Token missing required permissions (Copilot Chat, User copilot requests, Gists)
No active GitHub Copilot subscription
Token expired (Fine-grained PATs have expiration dates)

Test token manually:

  # Set your token
export GH_TOKEN="github_pat_your_token_here"

# Test API access
curl -H "Authorization: token $GH_TOKEN" \
  https://api.github.com/user

High Memory Usage

The Copilot CLI binary can use significant memory during analysis. If needed, limit container resources:

  services:
  gitlab-summary:
    # ... other config ...
    deploy:
      resources:
        limits:
          memory: 2G
        reservations:
          memory: 512M

Production Deployment

Security Best Practices

Use secrets management:
- Docker secrets
- Kubernetes secrets
- AWS Secrets Manager / Azure Key Vault / GCP Secret Manager
Enable HTTPS:
- Use reverse proxy (nginx, Traefik, Caddy)
- Terminate SSL at proxy level
Restrict network access:
- Use Docker networks
- Firewall rules for port 5100
- VPN or private network access only
Regular updates:
- Pull latest image weekly
- Monitor for security advisories
- Set up automated updates in CI/CD

Example Production docker-compose.yml

  services:
  gitlab-summary:
    image: garrardkitchen/gitlab-summary:latest
    container_name: gitlab-summary
    restart: always
    ports:
      - "127.0.0.1:5100:5100"  # Only accessible from localhost
    environment:
      - GITLAB_GROUP=${GITLAB_GROUP}
      - GITLAB_URL=${GITLAB_URL}
      - GITLAB_TOKEN=${GITLAB_TOKEN}
      - GITLAB_SINCE=24h
      - GITLAB_INTERVAL=30
    volumes:
      - gitlab-summary-data:/home/ubuntu/.local/share/gitlab-summary
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:5100/api/version"]
      interval: 30s
      timeout: 3s
      retries: 3
      start_period: 10s
    deploy:
      resources:
        limits:
          memory: 2G
        reservations:
          memory: 512M

volumes:
  gitlab-summary-data:
    driver: local

Monitoring

Health check endpoint:

  curl http://localhost:5100/api/version

Response:

  {
  "version": "0.2.5",
  "status": "healthy"
}

Prometheus metrics (if enabled):

  curl http://localhost:5100/metrics

Docker Compose Reference

Full Configuration Example

See the complete docker-compose.yml in the repository: https://github.com/garrardkitchen/gitlab-summary/blob/main/docker-compose.yml

Environment File (.env)

See .env.example for a complete template: https://github.com/garrardkitchen/gitlab-summary/blob/main/.env.example

Next Steps

Dashboard Overview

Installation

Docker Deployment

Docker Deployment link

Quick Start link

Using docker-compose (Recommended) link

Using docker run link

Linux/Windows - Named Volume link

macOS - Bind Mount link

Environment Variables link

Token Setup link

GitLab Token link

GitHub Token (Optional - for AI Analysis) link

Managing the Container link

View Logs link

Stop/Start/Restart link

Check Status link

Update to Latest Version link

Data Persistence link

Networking link

Custom Port link

Reverse Proxy link

Troubleshooting link

Container Won’t Start link

Dashboard Not Accessible link

AI Analysis Not Working link

High Memory Usage link

Production Deployment link

Security Best Practices link

Example Production docker-compose.yml link

Monitoring link

Docker Compose Reference link

Full Configuration Example link

Environment File (.env) link

Next Steps link

Docker Deployment

Quick Start

Using docker-compose (Recommended)

Using docker run

Linux/Windows - Named Volume

macOS - Bind Mount

Environment Variables

Token Setup

GitLab Token

GitHub Token (Optional - for AI Analysis)

Managing the Container

View Logs

Stop/Start/Restart

Check Status

Update to Latest Version

Data Persistence

Networking

Custom Port

Reverse Proxy

Troubleshooting

Container Won’t Start

Dashboard Not Accessible

AI Analysis Not Working

High Memory Usage

Production Deployment

Security Best Practices

Example Production docker-compose.yml

Monitoring

Docker Compose Reference

Full Configuration Example

Environment File (.env)

Next Steps