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. Create the default admin account automatically
6. 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. Create the default admin account automatically
5. Start the production server

Default Admin Account

The Docker build process automatically creates a default admin account with these credentials:

• Email: admin@localhost.com
• Password: admin123456
• Role: admin

⚠️ Important Security Note: Please change the default password immediately after your first login!

Manual Admin Account Creation

If you need to create the admin account manually (for development or testing):

# Using npm script
npm run create-admin

# Or directly
node scripts/create-admin.js

The script will skip creation if an admin account already exists.

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

Admin Account Issues

• If admin creation fails during build, check database initialization
• Ensure the database file is writable in the container
• If admin already exists, the script will skip creation (this is normal)
• To recreate admin account, delete the database and rebuild the container