feat(backend): build backend with Nix and add CI

2025-11-05 01:25:55 +01:00
parent e2b975fa12
commit 89c7588883
13 changed files with 594 additions and 25 deletions
--- a/.github/workflows/README.md
+++ b/.github/workflows/README.md
@@ -0,0 +1,217 @@
+# GitHub Actions Workflows
+
+## Docker Image Publishing
+
+The `publish-docker.yml` workflow automatically builds and publishes Docker images for the backend service using Nix.
+
+### Triggers and Tagging Strategy
+
+| Event        | Condition                   | Published Tags         | Example           |
+|--------------+-----------------------------+------------------------+-------------------|
+| Tag push     | Tag pushed to `main` branch | `latest` + version tag | `latest`, `1.0.0` |
+| Branch push  | Push to `develop` branch    | `develop`              | `develop`         |
+| Pull request | PR opened or updated        | `pr<number>`           | `pr12`            |
+| Branch push  | Push to `main` (no tag)     | `latest`               | `latest`          |
+
+### Required Secrets
+
+Configure these secrets in your repository settings (`Settings` → `Secrets and variables` → `Actions`):
+
+| Secret Name         | Description                                 | Example Value                           |
+|---------------------+---------------------------------------------+-----------------------------------------|
+| `DOCKER_USERNAME`   | Username for Docker registry authentication | `phundrak`                              |
+| `DOCKER_PASSWORD`   | Password or token for Docker registry       | Personal Access Token (PAT) or password |
+| `CACHIX_AUTH_TOKEN` | (Optional) Token for Cachix caching         | Your Cachix auth token                  |
+
+#### For GitHub Container Registry (ghcr.io)
+
+1. Create a Personal Access Token (PAT):
+   - Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
+   - Click "Generate new token (classic)"
+   - Select scopes: `write:packages`, `read:packages`, `delete:packages`
+   - Copy the generated token
+
+2. Add secrets:
+   - `DOCKER_USERNAME`: Your GitHub username
+   - `DOCKER_PASSWORD`: The PAT you just created
+
+#### For Docker Hub
+
+1. Create an access token:
+   - Go to Docker Hub → Account Settings → Security → Access Tokens
+   - Click "New Access Token"
+   - Set permissions to "Read, Write, Delete"
+   - Copy the generated token
+
+2. Add secrets:
+   - `DOCKER_USERNAME`: Your Docker Hub username
+   - `DOCKER_PASSWORD`: The access token you just created
+
+#### For Gitea Registry (e.g., labs.phundrak.com)
+
+1. Create an access token in Gitea:
+   - Log in to your Gitea instance
+   - Go to Settings (click your avatar → Settings)
+   - Navigate to Applications → Manage Access Tokens
+   - Click "Generate New Token"
+   - Give it a descriptive name (e.g., "Phundrak Labs Docker Registry")
+   - Select the required permissions:
+     - `write:package` - Required to publish packages
+     - `read:package` - Required to pull packages
+   - Click "Generate Token"
+   - Copy the generated token immediately (it won't be shown again)
+
+2. Add secrets:
+   - `DOCKER_USERNAME`: Your Gitea username
+   - `DOCKER_PASSWORD`: The access token you just created
+
+Note: Gitea's container registry is accessed at `https://your-gitea-instance/username/-/packages`
+
+#### For Other Custom Registries
+
+1. Obtain credentials from your registry administrator
+
+2. Add secrets:
+   - `DOCKER_USERNAME`: Your registry username
+   - `DOCKER_PASSWORD`: Your registry password or token
+
+### Configuring Cachix (Build Caching)
+
+Cachix is a Nix binary cache that dramatically speeds up builds by caching build artifacts. The workflow supports configurable Cachix settings.
+
+#### Environment Variables
+
+Configure these in the workflow's `env` section or as repository variables:
+
+| Variable           | Description                                    | Default Value | Example            |
+|--------------------+------------------------------------------------+---------------+--------------------|
+| `CACHIX_NAME`      | Name of the Cachix cache to use                | `devenv`      | `phundrak-dot-com` |
+| `CACHIX_SKIP_PUSH` | Whether to skip pushing artifacts to the cache | `true`        | `false`            |
+
+#### Option 1: Pull from Public Cache Only
+
+If you only want to pull from a public cache (no pushing):
+
+1. Set environment variables in the workflow:
+   ```yaml
+   env:
+     CACHIX_NAME: devenv  # or any public cache name
+     CACHIX_SKIP_PUSH: true
+   ```
+
+2. No `CACHIX_AUTH_TOKEN` secret is needed
+
+This is useful when using public caches like `devenv` or `nix-community`.
+
+#### Option 2: Use Your Own Cache (Recommended for Faster Builds)
+
+To cache your own build artifacts for faster subsequent builds:
+
+1. Create a Cachix cache:
+   - Go to https://app.cachix.org
+   - Sign up and create a new cache (e.g., `your-project-name`)
+   - Free for public/open-source projects
+
+2. Get your auth token:
+   - In Cachix, go to your cache settings
+   - Find your auth token under "Auth tokens"
+   - Copy the token
+
+3. Add your cache configuration to `flake.nix`:
+   ```nix
+   nixConfig = {
+     extra-trusted-public-keys = [
+       "devenv.cachix.org-1:w1cLUi8dv3hnoSPGAuibQv+f9TZLr6cv/Hm9XgU50cw="
+       "your-cache-name.cachix.org-1:YOUR_PUBLIC_KEY_HERE"
+     ];
+     extra-substituters = [
+       "https://devenv.cachix.org"
+       "https://your-cache-name.cachix.org"
+     ];
+   };
+   ```
+
+4. Configure the workflow:
+   - Edit `.github/workflows/publish-docker.yml`:
+     ```yaml
+     env:
+       CACHIX_NAME: your-cache-name
+       CACHIX_SKIP_PUSH: false
+     ```
+   - Or set as repository variables in GitHub/Gitea
+
+5. Add your auth token as a secret:
+   - Go to repository `Settings` → `Secrets and variables` → `Actions`
+   - Add secret `CACHIX_AUTH_TOKEN` with your token
+
+#### Benefits of Using Your Own Cache
+
+- **Faster builds**: Subsequent builds reuse cached artifacts (Rust dependencies, compiled binaries)
+- **Reduced CI time**: Can reduce build time from 10+ minutes to under 1 minute
+- **Cost savings**: Less compute time means lower CI costs
+- **Shared across branches**: All branches benefit from the same cache
+
+### Configuring the Docker Registry
+
+The target registry is set via the `DOCKER_REGISTRY` environment variable in the workflow file. To change it:
+
+1. Edit `.github/workflows/publish-docker.yml`
+2. Modify the `env` section:
+
+```yaml
+env:
+  DOCKER_REGISTRY: ghcr.io  # Change to your registry (e.g., docker.io, labs.phundrak.com)
+  IMAGE_NAME: phundrak/phundrak-dot-com-backend
+```
+
+Or set it as a repository variable:
+- Go to `Settings` → `Secrets and variables` → `Actions` → `Variables` tab
+- Add `DOCKER_REGISTRY` with your desired registry URL
+
+### Image Naming
+
+Images are published with the name: `${DOCKER_REGISTRY}/${IMAGE_NAME}:${TAG}`
+
+For example:
+- `labs.phundrak.com/phundrak/phundrak-dot-com-backend:latest`
+- `labs.phundrak.com/phundrak/phundrak-dot-com-backend:1.0.0`
+- `labs.phundrak.com/phundrak/phundrak-dot-com-backend:develop`
+- `labs.phundrak.com/phundrak/phundrak-dot-com-backend:pr12`
+
+### Local Testing
+
+To test the Docker image build locally:
+
+```bash
+# Build the image with Nix
+nix build .#backendDockerLatest
+
+# Load it into Docker
+docker load < result
+
+# Run the container (image name comes from Cargo.toml package.name)
+docker run -p 3100:3100 phundrak/phundrak-dot-com-backend:latest
+```
+
+### Troubleshooting
+
+#### Authentication Failures
+
+If you see authentication errors:
+1. Verify your `DOCKER_USERNAME` and `DOCKER_PASSWORD` secrets are correct
+2. For ghcr.io, ensure your PAT has the correct permissions
+3. Check that the `DOCKER_REGISTRY` matches your credentials
+
+#### Build Failures
+
+If the Nix build fails:
+1. Test the build locally first: `nix build .#backendDockerLatest`
+2. Check the GitHub Actions logs for specific error messages
+3. Ensure all dependencies in `flake.nix` are correctly specified
+
+#### Image Not Appearing in Registry
+
+1. Verify the workflow completed successfully in the Actions tab
+2. Check that the registry URL is correct
+3. For ghcr.io, images appear at: `https://github.com/users/USERNAME/packages/container/IMAGE_NAME`
+4. Ensure your token has write permissions
--- a/.github/workflows/publish-docker.yml
+++ b/.github/workflows/publish-docker.yml
@@ -0,0 +1,123 @@
+name: Publish Docker Images
+
+on:
+  push:
+    branches:
+      - main
+      - develop
+    tags:
+      - 'v*.*.*'
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+env:
+  CACHIX_NAME: devenv
+  CACHIX_SKIP_PUSH: true
+  DOCKER_REGISTRY: labs.phundrak.com  # Override in repository settings if needed
+  IMAGE_NAME: phundrak/phundrak-dot-com-backend
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write  # Required for pushing to Phundrak Labs registry
+      pull-requests: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install Nix
+        uses: cachix/install-nix-action@v27
+        with:
+          nix_path: nixpkgs=channel:nixos-unstable
+
+      - name: Setup Cachix
+        uses: cachix/cachix-action@v15
+        with:
+          name: '${{ env.CACHIX_NAME }}'
+          authToken: '${{ secrets.CACHIX_AUTH_TOKEN }}'
+          skipPush: ${{ env.CACHIX_SKIP_PUSH }}
+
+      - name: Build Docker image with Nix
+        run: |
+          echo "Building Docker image..."
+          nix build .#backendDockerLatest --accept-flake-config
+
+      - name: Load Docker image
+        run: |
+          echo "Loading Docker image into Docker daemon..."
+          docker load < result
+
+      - name: Log in to Docker Registry
+        run: |
+          echo "${{ secrets.DOCKER_PASSWORD }}" | docker login ${{ env.DOCKER_REGISTRY }} -u ${{ secrets.DOCKER_USERNAME }} --password-stdin
+
+      - name: Determine tags and push images
+        run: |
+          set -euo pipefail
+
+          REGISTRY="${{ env.DOCKER_REGISTRY }}"
+          IMAGE_NAME="${{ env.IMAGE_NAME }}"
+
+          # The locally built image from Nix (name comes from Cargo.toml package.name)
+          LOCAL_IMAGE="phundrak/phundrak-dot-com-backend:latest"
+
+          echo "Event: ${{ github.event_name }}"
+          echo "Ref: ${{ github.ref }}"
+          echo "Ref type: ${{ github.ref_type }}"
+
+          # Determine which tags to push based on the event
+          if [[ "${{ github.event_name }}" == "push" && "${{ github.ref_type }}" == "tag" ]]; then
+            # Tag push on main branch → publish 'latest' and versioned tag
+            echo "Tag push detected"
+            TAG_VERSION="${{ github.ref_name }}"
+            # Remove 'v' prefix if present (v1.0.0 → 1.0.0)
+            TAG_VERSION="${TAG_VERSION#v}"
+
+            echo "Tagging and pushing: ${REGISTRY}/${IMAGE_NAME}:latest"
+            docker tag "${LOCAL_IMAGE}" "${REGISTRY}/${IMAGE_NAME}:latest"
+            docker push "${REGISTRY}/${IMAGE_NAME}:latest"
+
+            echo "Tagging and pushing: ${REGISTRY}/${IMAGE_NAME}:${TAG_VERSION}"
+            docker tag "${LOCAL_IMAGE}" "${REGISTRY}/${IMAGE_NAME}:${TAG_VERSION}"
+            docker push "${REGISTRY}/${IMAGE_NAME}:${TAG_VERSION}"
+
+          elif [[ "${{ github.event_name }}" == "push" && "${{ github.ref }}" == "refs/heads/develop" ]]; then
+            # Push on develop branch → publish 'develop' tag
+            echo "Push to develop branch detected"
+
+            echo "Tagging and pushing: ${REGISTRY}/${IMAGE_NAME}:develop"
+            docker tag "${LOCAL_IMAGE}" "${REGISTRY}/${IMAGE_NAME}:develop"
+            docker push "${REGISTRY}/${IMAGE_NAME}:develop"
+
+          elif [[ "${{ github.event_name }}" == "pull_request" ]]; then
+            # Pull request → publish 'pr<number>' tag
+            echo "Pull request detected"
+            PR_NUMBER="${{ github.event.pull_request.number }}"
+
+            echo "Tagging and pushing: ${REGISTRY}/${IMAGE_NAME}:pr${PR_NUMBER}"
+            docker tag "${LOCAL_IMAGE}" "${REGISTRY}/${IMAGE_NAME}:pr${PR_NUMBER}"
+            docker push "${REGISTRY}/${IMAGE_NAME}:pr${PR_NUMBER}"
+
+          elif [[ "${{ github.event_name }}" == "push" && "${{ github.ref }}" == "refs/heads/main" ]]; then
+            # Push to main branch (not a tag) → publish 'latest'
+            echo "Push to main branch detected"
+
+            echo "Tagging and pushing: ${REGISTRY}/${IMAGE_NAME}:latest"
+            docker tag "${LOCAL_IMAGE}" "${REGISTRY}/${IMAGE_NAME}:latest"
+            docker push "${REGISTRY}/${IMAGE_NAME}:latest"
+
+          else
+            echo "Unknown event or ref, skipping push"
+            exit 1
+          fi
+
+      - name: Log out from Docker Registry
+        if: always()
+        run: docker logout ${{ env.DOCKER_REGISTRY }}
+
+      - name: Image published successfully
+        run: |
+          echo "✅ Docker image(s) published successfully to ${{ env.DOCKER_REGISTRY }}/${{ env.IMAGE_NAME }}"