panel/DOCKER_GIT_DEPLOYMENT.md

Docker Git Deployment Guide

This project now supports deploying directly from a Git repository using Docker. This is useful for automated deployments and CI/CD pipelines.

File Structure

• Dockerfile - Production dockerfile that supports Git deployment
• Dockerfile.dev - Development dockerfile
• docker-compose.yml - Development environment
• docker-compose.prod.yml - Production environment with Git support
• deploy.sh / deploy.bat - Deployment scripts

Deployment Options

1. Deploy from Local Files (Default)

# Development
docker-compose up

# Production
docker-compose -f docker-compose.prod.yml up --build

2. Deploy from Git Repository

Using Environment Variables

Create a .env file with:

GIT_REPO_URL=https://github.com/yourusername/your-repo.git
GIT_BRANCH=main
GIT_COMMIT=abc123  # Optional: specific commit hash

Then run:

docker-compose -f docker-compose.prod.yml up --build

Using Build Arguments

docker build \
  --build-arg GIT_REPO_URL=https://github.com/yourusername/your-repo.git \
  --build-arg GIT_BRANCH=main \
  --build-arg GIT_COMMIT=abc123 \
  -t your-app .

Using Deployment Scripts

# Linux/Mac
./deploy.sh https://github.com/yourusername/your-repo.git main abc123

# Windows
deploy.bat https://github.com/yourusername/your-repo.git main abc123

Private Repositories

For private repositories, you have several options:

1. SSH Keys (Recommended for development)

# Build with SSH URL
docker build --build-arg GIT_REPO_URL=git@github.com:yourusername/your-repo.git .

2. Personal Access Token

# Build with token in URL
docker build --build-arg GIT_REPO_URL=https://token@github.com/yourusername/your-repo.git .

3. Docker Secrets (Recommended for production)

# In docker-compose.prod.yml
services:
  app:
    build:
      context: .
      args:
        - GIT_REPO_URL=https://github.com/yourusername/your-repo.git
      secrets:
        - git_token
secrets:
  git_token:
    file: ./git_token.txt

CI/CD Integration

GitHub Actions Example

name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to server
        run: |
          docker build \
            --build-arg GIT_REPO_URL=${{ github.repository }} \
            --build-arg GIT_COMMIT=${{ github.sha }} \
            -t my-app .
          docker run -d -p 3000:3000 my-app

Docker Compose in CI/CD

# Set environment variables in your CI/CD system
export GIT_REPO_URL="https://github.com/yourusername/your-repo.git"
export GIT_BRANCH="main"
export GIT_COMMIT="$CI_COMMIT_SHA"

# Deploy
docker-compose -f docker-compose.prod.yml up --build -d

Build Process

When GIT_REPO_URL is provided:

1. Git repository is cloned into the container
2. If GIT_COMMIT is specified, checkout that specific commit
3. Install dependencies from the repository's package.json
4. Build the application
5. Start the production server

When GIT_REPO_URL is not provided:

1. Copy local files into the container
2. Install dependencies
3. Build the application
4. Start the production server

Environment Variables

• GIT_REPO_URL - Git repository URL (HTTPS or SSH)
• GIT_BRANCH - Git branch to checkout (default: main)
• GIT_COMMIT - Specific commit hash to checkout (optional)
• NODE_ENV - Node.js environment (development/production)

Troubleshooting

Git Authentication Issues

• Ensure your Git credentials are properly configured
• For HTTPS, use personal access tokens instead of passwords
• For SSH, ensure SSH keys are properly mounted or available

Build Failures

• Check if the repository URL is accessible
• Verify the branch name exists
• Ensure the commit hash is valid
• Check Docker build logs for specific errors

Permission Issues

• Ensure the Docker daemon has network access
• For private repositories, verify authentication tokens/keys