# Deployment Setup

This document explains how to configure the GitHub Actions deployment workflow for the VOKO Django application.

## Overview

The deployment workflow (`deploy.yml`) supports:
- **Automatic deployment to test environment** when pushing to the `main` branch
- **Manual deployment** to either test or production environments via workflow dispatch
- **Branch selection** for manual deployments

## Required GitHub Secrets

To use the deployment workflow, you need to configure the following secrets in your GitHub repository settings:

### Environment-Specific Secrets

The workflow uses GitHub Environments (`test` and `production`) to manage secrets. Configure the following secrets for each environment:

#### For Test Environment
Go to: Repository Settings → Environments → test → Add Secret

- `HOST` - The hostname/IP address of your test server
- `USERNAME` - SSH username for the test server
- `SSH_KEY` - Private SSH key for authentication (see SSH Key Setup below)
- `PORT` - SSH port (optional, defaults to 22)

#### For Production Environment
Go to: Repository Settings → Environments → production → Add Secret

- `HOST` - The hostname/IP address of your production server
- `USERNAME` - SSH username for the production server
- `SSH_KEY` - Private SSH key for authentication (see SSH Key Setup below)
- `PORT` - SSH port (optional, defaults to 22)

## SSH Key Setup

1. **Generate an SSH key pair** (if you don't have one):
   ```bash
   ssh-keygen -t ed25519 -C "github-actions-deploy" -f ~/.ssh/voko_deploy_key
   ```

2. **Add the public key to your server(s)**:
   ```bash
   # Copy the public key to your server's authorized_keys
   cat ~/.ssh/voko_deploy_key.pub >> ~/.ssh/authorized_keys
   ```

3. **Add the private key to GitHub Secrets**:
   - Copy the contents of the private key file:
     ```bash
     cat ~/.ssh/voko_deploy_key
     ```
   - Paste this content into the `SSH_KEY` secret in GitHub

## Server Requirements

Your server(s) must have:
- The `deploy.sh` script located at `$HOME/scripts/deploy.sh`
- Git repository cloned at `$HOME/voko`
- Proper permissions for the deploy user to run the script
- `uv` package manager installed
- Systemctl permissions to restart gunicorn service

## Deployment Triggers

### Automatic Deployment (Test Environment)
- **Trigger**: Push to `main` branch
- **Target**: Test environment
- **Branch deployed**: `main` (always)

### Manual Deployment
- **Trigger**: Workflow dispatch (manually triggered from GitHub Actions tab)
- **Target**: Choose between test or production environment
- **Branch deployed**: Any branch you specify

## How to Deploy Manually

1. Go to your repository on GitHub
2. Click on the "Actions" tab
3. Select the "Deploy" workflow
4. Click "Run workflow"
5. Choose:
   - **Branch to deploy**: The git branch you want to deploy
   - **Environment**: Either `test` or `production`
6. Click "Run workflow"

## Deploy Script

The deployment workflow calls the `deploy.sh` script on your server with the `-b` flag to specify the branch:

```bash
$HOME/scripts/deploy.sh -b <branch_name>
```

The script performs:
- Git checkout to specified branch
- Git pull to get latest changes
- UV sync to install/update dependencies
- Database migrations
- Static file collection
- Gunicorn service restart

## Security Considerations

- Use separate SSH keys for test and production environments
- Consider using different users for test and production deployments
- Limit SSH key permissions to only what's needed for deployment
- Use GitHub Environment protection rules for production deployments
- Consider requiring reviews for production deployments

## Troubleshooting

### SSH Connection Issues
- Verify the SSH key is correctly formatted in GitHub Secrets
- Ensure the public key is properly added to the server's `~/.ssh/authorized_keys`
- Check that the hostname/IP and port are correct
- Verify SSH access manually: `ssh -i private_key username@hostname`

### Deploy Script Issues
- Ensure the script has execute permissions: `chmod +x $HOME/scripts/deploy.sh`
- Verify the script path exists on the server
- Check that all script dependencies (git, uv, systemctl) are available
- Review server logs for detailed error messages

### GitHub Actions Issues
- Check the Actions tab for detailed error logs
- Verify all required secrets are configured
- Ensure environment names match exactly: `test` and `production`

Author: tobiascadee

.github/workflows/deploy.yml

@@ -0,0 +1,55 @@
+---
+name: Deploy
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+    inputs:
+      branch:
+        description: 'Branch to deploy'
+        required: true
+        default: 'main'
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  deploy-test:
+    name: Deploy to test environment
+    runs-on: ubuntu-latest
+    environment: test
+    if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
+
+    
+    steps:
+      - name: Deploy to test server
+        uses: appleboy/[email protected]
+        with:
+          key: ${{ secrets.SSH_KEY }}
+          script: |
+            # Run the deploy script with the specified branch
+            if [ "${{ github.event_name }}" = "push" ]; then
+              # Auto-deploy to test environment on push to main
+              $HOME/scripts/deploy.sh -b main
+            else
+              # Manual deploy with specified branch
+              $HOME/scripts/deploy.sh -b ${{ github.event.inputs.branch }}
+            fi
+
+  deploy-production:
+    name: Deploy to production environment
+    runs-on: ubuntu-latest
+    environment: production
+    if: github.event_name == 'push'
+    
+    steps:
+      - name: Deploy to production server
+        uses: appleboy/[email protected]
+        with:
+          key: ${{ secrets.SSH_KEY }}
+          script: |
+            # Run the deploy script with the specified branch
+            $HOME/scripts/deploy.sh -b ${{ github.event.inputs.branch }}

README.md

@@ -3,6 +3,14 @@ Django based custom web application for food collective www.vokoutrecht.nl.
 
 ![example workflow](https://github.com/VOKO-Utrecht/voko/actions/workflows/ci.yml/badge.svg)
 
+## Deployment
+
+This project includes automated deployment workflows:
+- **Test environment**: Automatically deploys when pushing to `main` branch
+- **Production environment**: Manual deployment via GitHub Actions workflow dispatch
+
+For complete deployment setup instructions, see [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md).
+
 ## Some notes
 1. The code base needs cleaning up and adding of tests.
 2. License: GNU GPLv3