Add automated deployment via GitHub Actions

- Add GitHub Actions workflow for automated deployment on push to main
- Create deploy.sh script for production server deployment
- Update CLAUDE.md with comprehensive CI/CD documentation
- Add DEPLOYMENT_SETUP.md with step-by-step setup instructions
- Configure .github directory in Claude workspace

Deployment flow: Codespaces → git push → GitHub Actions → Hetzner VM

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: roberteinsle

.claude/settings.local.json

@@ -74,6 +74,9 @@
       "Read(//tmp/**)",
       "Bash(md5sum:*)",
       "Bash(xargs awk:*)"
+    ],
+    "additionalDirectories": [
+      "/workspaces/leafmark/.github"
     ]
   }
 }

.github/workflows/deploy.yml

@@ -0,0 +1,23 @@
+name: Deploy to Production
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  deploy:
+    name: Deploy to Hetzner VM
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Deploy to Production Server
+        uses: appleboy/ssh-action@v1.0.3
+        with:
+          host: ${{ secrets.PROD_HOST }}
+          username: ${{ secrets.PROD_USER }}
+          key: ${{ secrets.PROD_SSH_KEY }}
+          port: ${{ secrets.PROD_SSH_PORT }}
+          script: |
+            cd /opt/leafmark
+            bash deploy.sh

CLAUDE.md

@@ -432,19 +432,200 @@ The Docker entrypoint ([docker-entrypoint.sh](docker-entrypoint.sh)) automatical
 - `storage_data` - Uploaded book covers
 - `vendor` - Composer dependencies
 
+## CI/CD & Automated Deployment
+
+The application uses **GitHub Actions** for automated deployment to production when code is pushed to the `main` branch.
+
+### Deployment Workflow
+
+**Development → Production Flow:**
+1. Development happens in **GitHub Codespaces** (https://silver-space-orbit-xx4x79vwgpcvpp.github.dev/)
+2. Developer manually commits and pushes changes to GitHub (`git push`)
+3. GitHub Actions automatically triggers deployment
+4. Production server pulls latest code and restarts containers
+
+**Automated Deployment Process:**
+- Triggered on: `git push` to `main` branch
+- GitHub Actions workflow: [.github/workflows/deploy.yml](.github/workflows/deploy.yml)
+- Deployment script: [deploy.sh](deploy.sh) (runs on production server)
+- No manual intervention required after push
+
+### Production Server Details
+
+**Server Environment:**
+- Provider: Hetzner VM
+- User: `deploy`
+- Application directory: `/opt/leafmark`
+- Git repository: Cloned from `https://github.com/roberteinsle/leafmark.git`
+
+**Directory Structure:**
+```
+/opt/leafmark/
+├── docker-compose.yaml    # Docker configuration
+├── Dockerfile            # App container build instructions
+├── deploy.sh             # Deployment script (executable)
+└── [Laravel application files...]
+```
+
+### Initial Production Setup
+
+**Prerequisites on Hetzner VM:**
+```bash
+# Install Docker and Docker Compose
+curl -fsSL https://get.docker.com -o get-docker.sh
+sudo sh get-docker.sh
+sudo usermod -aG docker deploy
+
+# Install Git
+sudo apt update
+sudo apt install -y git
+```
+
+**Setup deployment user and repository:**
+```bash
+# Login as deploy user
+sudo su - deploy
+
+# Create application directory
+sudo mkdir -p /opt/leafmark
+sudo chown deploy:deploy /opt/leafmark
+cd /opt/leafmark
+
+# Clone repository
+git clone https://github.com/roberteinsle/leafmark.git .
+
+# Make deployment script executable
+chmod +x deploy.sh
+
+# Configure environment (if not already done)
+# See "Initial Server Setup" section below for .env configuration
+```
+
+**Setup GitHub Actions SSH Access:**
+
+1. Generate SSH key pair on your local machine:
+```bash
+ssh-keygen -t ed25519 -C "github-actions-deploy" -f ~/.ssh/leafmark_deploy
+```
+
+2. Copy public key to production server:
+```bash
+ssh-copy-id -i ~/.ssh/leafmark_deploy.pub deploy@YOUR_SERVER_IP
+```
+
+3. Add GitHub Secrets (GitHub Repository → Settings → Secrets and variables → Actions):
+   - `PROD_HOST` - Production server IP address
+   - `PROD_USER` - `deploy`
+   - `PROD_SSH_KEY` - Contents of private key file (`cat ~/.ssh/leafmark_deploy`)
+   - `PROD_SSH_PORT` - SSH port (usually `22`)
+
+**Test SSH connection:**
+```bash
+ssh -i ~/.ssh/leafmark_deploy deploy@YOUR_SERVER_IP "cd /opt/leafmark && pwd"
+```
+
+### Deployment Script Details
+
+The [deploy.sh](deploy.sh) script performs these steps:
+
+1. **Pull latest code** from GitHub (`git pull origin main`)
+2. **Stop containers** (`docker compose down`)
+3. **Rebuild containers** (`docker compose up -d --build`)
+4. **Wait for startup** (10 seconds)
+5. **Run migrations** (`php artisan migrate --force`)
+6. **Clear caches** (`config:cache`, `route:cache`, `view:cache`)
+7. **Verify storage symlink** (`storage:link`)
+
+**Key Features:**
+- Preserves Docker volumes (database and uploaded files are NOT deleted)
+- Automatic migration execution
+- Cache clearing for updated routes/config
+- Logs deployment timestamp and status
+
+### Manual Deployment
+
+If you need to deploy manually without pushing to GitHub:
+
+```bash
+# SSH into production server
+ssh deploy@YOUR_SERVER_IP
+
+# Navigate to application directory
+cd /opt/leafmark
+
+# Run deployment script
+bash deploy.sh
+```
+
+### Deployment Monitoring
+
+**View deployment logs in GitHub:**
+1. Go to repository → Actions tab
+2. Select the latest workflow run
+3. View deployment logs and status
+
+**View application logs on server:**
+```bash
+# SSH into server
+ssh deploy@YOUR_SERVER_IP
+
+# View Docker container logs
+cd /opt/leafmark
+docker compose logs -f app
+```
+
+### Rollback Procedure
+
+If deployment fails and you need to rollback:
+
+```bash
+# SSH into production server
+ssh deploy@YOUR_SERVER_IP
+cd /opt/leafmark
+
+# Check git log for previous commit
+git log --oneline -n 5
+
+# Rollback to previous commit (replace COMMIT_HASH)
+git reset --hard COMMIT_HASH
+
+# Re-run deployment script
+bash deploy.sh
+```
+
+**⚠️ WARNING:** Rolling back code does NOT rollback database migrations. If new migrations were run, you may need to manually rollback migrations:
+```bash
+docker compose exec app php artisan migrate:rollback
+```
+
 ## Production Deployment
 
+**Note:** This section describes manual production setup. For automated deployment via GitHub Actions, see [CI/CD & Automated Deployment](#cicd--automated-deployment).
+
+**Production Server:**
+- Server: Hetzner VM
+- User: `deploy`
+- Location: `/opt/leafmark`
+- Automated deployment: Enabled via GitHub Actions
+
 ### Initial Server Setup
 
 ```bash
+# Login as deploy user
+sudo su - deploy
+
 # Create directory and clone repository
-cd ~/leafmark
-git clone https://github.com/roberteinsle/leafmark.git app-source
-cd app-source
+sudo mkdir -p /opt/leafmark
+sudo chown deploy:deploy /opt/leafmark
+cd /opt/leafmark
+git clone https://github.com/roberteinsle/leafmark.git .
 
 # Create and configure .env
 cp .env.example .env
 nano .env
+
+# Make deployment script executable
+chmod +x deploy.sh
 ```
 
 **Environment variables are set via docker-compose.yaml:**
@@ -506,10 +687,24 @@ Then configure registration settings:
 
 ### Update Workflow
 
-To update the application:
+**⚠️ IMPORTANT:** Updates are now **automated via GitHub Actions**. Simply push to `main` branch and deployment happens automatically.
 
+**Automated deployment** (recommended):
+1. Push changes to GitHub: `git push origin main`
+2. GitHub Actions automatically deploys to production
+3. No manual intervention required
+
+**Manual deployment** (if needed):
 ```bash
-cd ~/leafmark/app-source
+cd /opt/leafmark
+
+# Run deployment script (does everything automatically)
+bash deploy.sh
+```
+
+**Manual step-by-step** (for troubleshooting only):
+```bash
+cd /opt/leafmark
 
 # Pull latest code from GitHub
 git pull origin main