Add GHCR Docker authentication guide

2026-01-15 09:48:58 +01:00
parent 36a26f55c2
commit df5bf6801e
3 changed files with 184 additions and 20 deletions
--- a/DEPLOYMENT.md
+++ b/DEPLOYMENT.md
@@ -121,20 +121,78 @@ Your JWT secret is stored in the `.env` file which is protected by `.gitignore`

 ## Deployment

-### 1. Log in to GHCR
+### 1. Configure Docker Authentication to GHCR
+
+You need to authenticate Docker to pull private images from GitHub Container Registry (GHCR). Choose one of these methods:
+
+#### Option A: Store Credentials in `/etc/docker/daemon.json` (Recommended for Docker Services)
+
+This approach is recommended if you're using Dockge, systemd services, or other Docker management tools that run as services. The credentials are stored globally so all Docker processes can use them.
+
+**Step 1: Generate base64-encoded credentials**
+```bash
+# Replace with your actual GitHub username and token
+echo -n "YOUR_GITHUB_USERNAME:YOUR_GITHUB_TOKEN" | base64
+
+# Output example:
+# WU9VUl9HSVRIVUJfVVNFUk5BTUU6WU9VUl9HSVRIVUJfVE9LRU4=
+```
+
+**Step 2: Update Docker daemon configuration**
+```bash
+sudo nano /etc/docker/daemon.json
+```
+
+Add or update the `auths` section. The full file should look like:
+```json
+{
+  "auths": {
+    "ghcr.io": {
+      "auth": "YOUR_BASE64_CREDENTIALS_HERE"
+    }
+  }
+}
+```
+
+**Step 3: Restart Docker**
+```bash
+sudo systemctl restart docker
+
+# Wait a few seconds for Docker to restart
+sleep 3
+
+# Verify authentication works
+docker pull ghcr.io/YOUR_GITHUB_USER/edh-stats-backend:latest
+```
+
+#### Option B: Interactive Docker Login (Simpler but User-Specific)
+
+Use this if you're deploying manually and don't have other services pulling images.

 ```bash
-echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin
+docker login ghcr.io
+
+# You'll be prompted for:
+# Username: YOUR_GITHUB_USERNAME
+# Password: YOUR_GITHUB_TOKEN (NOT your GitHub password!)
+
+# Verify login worked
+docker pull ghcr.io/YOUR_GITHUB_USER/edh-stats-backend:latest
 ```

+**Note:** With this approach, credentials are stored in `~/.docker/config.json` and only the current user can use them. If Docker runs as a different user (like in Dockge), authentication will fail.
+
 ### 2. Pull Latest Images

 ```bash
 cd ~/edh-stats

-# Pull images
+# Pull images (this will use credentials from daemon.json or docker login)
 docker pull ghcr.io/YOUR_GITHUB_USER/edh-stats-backend:latest
 docker pull ghcr.io/YOUR_GITHUB_USER/edh-stats-frontend:latest
+
+# If pull fails, verify authentication
+docker pull ghcr.io/YOUR_GITHUB_USER/edh-stats-backend:v1.0.0
 ```

 ### 3. Start Services
@@ -294,16 +352,74 @@ curl -s http://localhost/ | head -20

 ## Troubleshooting

-### Images Won't Pull
+### Images Won't Pull / "Unauthorized" Error

+**Error Example:**
+```
+Error response from daemon: Head "https://ghcr.io/v2/...": unauthorized
+```
+
+This usually means Docker isn't authenticated to pull from GHCR.
+
+**Solution 1: Verify daemon.json Configuration (Recommended)**
 ```bash
-# Verify GHCR login
-docker login ghcr.io
+# Check the configuration file
+cat /etc/docker/daemon.json

-# Check image exists
+# Should contain valid base64 credentials for ghcr.io
+# If missing or malformed, edit it:
+sudo nano /etc/docker/daemon.json
+
+# Then restart Docker
+sudo systemctl restart docker
+
+# Test pull
 docker pull ghcr.io/YOUR_GITHUB_USER/edh-stats-backend:latest
 ```

+**Solution 2: Use Interactive Login**
+```bash
+docker login ghcr.io
+# Username: YOUR_GITHUB_USERNAME
+# Password: YOUR_GITHUB_TOKEN (NOT your password!)
+
+# Verify login worked
+docker pull ghcr.io/YOUR_GITHUB_USER/edh-stats-backend:latest
+```
+
+**Solution 3: Test with a Public Image First**
+```bash
+# If pulling private images fails, test with a public image
+docker pull nginx:latest
+
+# If this works, your Docker daemon is OK
+# If this fails, restart Docker: sudo systemctl restart docker
+```
+
+**Solution 4: Check Token Scope**
+```bash
+# Make sure your GitHub token has read:packages scope
+# Go to: https://github.com/settings/tokens
+# Click on the token and verify it has:
+# - read:packages
+# - write:packages (for pushing)
+```
+
+**Solution 5: For Dockge or Other Services**
+```bash
+# If Dockge or other services can't pull, ensure daemon.json is used
+# Not ~/.docker/config.json which is user-specific
+
+# Check who's running Docker
+ps aux | grep docker
+
+# Verify /etc/docker/daemon.json has correct permissions
+ls -l /etc/docker/daemon.json
+
+# Restart Docker to apply daemon.json changes
+sudo systemctl restart docker
+```
+
 ### Services Won't Start

 ```bash
--- a/PRODUCTION_RELEASE.md
+++ b/PRODUCTION_RELEASE.md
@@ -94,14 +94,16 @@ git push origin v1.0.0
 - Docker secret files
 - SSL/TLS certificates
 - JWT_SECRET values
+- `/etc/docker/daemon.json` (contains base64-encoded GHCR credentials)

 All are properly in `.gitignore` ✓

 ### Required Before Deployment
- [ ] GitHub Personal Access Token with `write:packages` scope
+- [ ] GitHub Personal Access Token with `write:packages` and `read:packages` scopes
 - [ ] Secure JWT secret (generated via `openssl rand -base64 32`)
 - [ ] Domain name with DNS configured
 - [ ] SSL certificates (Let's Encrypt is free)
+- [ ] Docker authentication configured (see QUICK_DEPLOY.md step 5)

 ### Production Settings
 - `NODE_ENV=production` ✓
--- a/QUICK_DEPLOY.md
+++ b/QUICK_DEPLOY.md
@@ -140,16 +140,50 @@ chmod 600 .env

 **Note:** The `.env` file is already in `.gitignore` so it won't be committed to git.

-### 5. Start Services
+### 5. Configure Docker Authentication to GHCR
+
+**Option A: Store Credentials in `/etc/docker/daemon.json` (Recommended for Services)**
+
+This approach stores credentials globally so Docker services (including Dockge) can pull images without interactive login.

-**Pull Latest Images:**
 ```bash
-docker login ghcr.io  # Use your GitHub token as password
+# Generate base64-encoded credentials
+echo -n "YOUR_GITHUB_USERNAME:YOUR_GITHUB_TOKEN" | base64
+# Output example: WU9VUl9HSVRIVUJfVVNFUk5BTUU6WU9VUl9HSVRIVUJfVE9LRU4=

-docker pull ghcr.io/YOUR_GITHUB_USER/edh-stats-backend:v1.0.0
-docker pull ghcr.io/YOUR_GITHUB_USER/edh-stats-frontend:v1.0.0
+# Edit Docker daemon configuration
+sudo nano /etc/docker/daemon.json
 ```

+Add or update the `auths` section in `/etc/docker/daemon.json`:
+```json
+{
+  "auths": {
+    "ghcr.io": {
+      "auth": "YOUR_BASE64_CREDENTIALS_HERE"
+    }
+  }
+}
+```
+
+Then restart Docker:
+```bash
+sudo systemctl restart docker
+```
+
+**Option B: Interactive Docker Login (Simpler but Service-Specific)**
+
+```bash
+docker login ghcr.io
+# Username: YOUR_GITHUB_USERNAME
+# Password: YOUR_GITHUB_TOKEN (NOT your GitHub password!)
+
+# Verify login worked
+docker pull ghcr.io/YOUR_GITHUB_USER/edh-stats-backend:v1.0.0
+```
+
+### 6. Start Services
+
 **Start Docker Compose:**
 ```bash
 docker-compose up -d
@@ -173,7 +207,7 @@ curl http://localhost/
 docker-compose logs -f backend
 ```

-### 6. Configure SSL (Optional but Recommended)
+### 7. Configure SSL (Optional but Recommended)

 **Install Certbot:**
 ```bash
@@ -203,7 +237,7 @@ ssl_certificate_key /etc/nginx/certs/privkey.pem;
 docker-compose up -d
 ```

-### 7. Setup Auto-Renewal (SSL)
+### 8. Setup Auto-Renewal (SSL)

 **Create renewal script:**
 ```bash
@@ -224,7 +258,7 @@ crontab -e
 0 2 1 * * /home/user/renew-ssl.sh
 ```

-### 8. Verify Everything Works
+### 9. Verify Everything Works

 **Test the Application:**
 ```bash
@@ -274,15 +308,27 @@ docker-compose down
 docker-compose up -d
 ```

-### Can't Login to GHCR
+### Can't Pull Images from GHCR
 ```bash
-# Verify token
+# Error: "unauthorized" when pulling images
+
+# Solution 1: Check if Docker is authenticated
 docker login ghcr.io
 # Username: YOUR_GITHUB_USERNAME
-# Password: YOUR_GITHUB_TOKEN (not your password!)
+# Password: YOUR_GITHUB_TOKEN (NOT your GitHub password!)

-# Test login
+# Solution 2: For Docker services (Dockge, systemd, etc.)
+# Use daemon.json approach instead (see step 5 Option A)
+
+# Verify /etc/docker/daemon.json has correct format:
+cat /etc/docker/daemon.json
+
+# Test pull after authentication
 docker pull ghcr.io/YOUR_USER/edh-stats-backend:v1.0.0
+
+# If still failing, restart Docker
+sudo systemctl restart docker
+docker-compose pull
 ```

 ### Frontend Shows Blank Page