krops-multi-deploy/DEPLOYMENT-GUIDE.md

Web-App Deployment Guide

Overview

This setup builds the web-app locally with machine-specific configuration, then deploys the built artifacts to each target machine. Each machine gets its own customized build with:

• Machine-specific .env files
• Machine-specific images in the public folder

Structure

.
├── web-app/                          # Shared web-app source code
│   ├── package.json
│   ├── index.html
│   └── public/                       # Base public folder
├── machine-specific/
│   ├── machine1/
│   │   ├── env/.env                  # Machine1's environment file
│   │   └── images/                   # Machine1's images
│   │       ├── logo.png
│   │       └── banner.jpg
│   └── machine2/
│       ├── env/.env                  # Machine2's environment file
│       └── images/                   # Machine2's images
│           ├── logo.png
│           └── banner.jpg
├── build/                            # Generated locally (gitignored)
│   ├── machine1/dist/                # Built files for machine1
│   └── machine2/dist/                # Built files for machine2
├── build-local.nix                   # Local build scripts
└── krops.nix                         # Deployment configuration

How It Works

1. Build Locally

First, build the web-app for each machine on your local machine:

# Build for a specific machine
nix-build ./build-local.nix -A machine1 && ./result/bin/build-machine1

# Or build for all machines
nix-build ./build-local.nix -A all && ./result/bin/build-all

This:

1. Copies web-app source to ./build/{machine}/
2. Copies machine-specific .env file
3. Copies machine-specific images to public/
4. Runs npm run build
5. Creates ./build/{machine}/dist/ with the built app

2. Deploy Built Artifacts

After building, deploy to target machines:

# Deploy to specific machine
nix-build ./krops.nix -A machine1 && ./result

# Deploy to all machines
nix-build ./krops.nix -A all && ./result

The built files from ./build/{machine}/dist/ are copied to /var/src/web-app-dist/ on each target machine.

Complete Workflow

# 1. Build locally for all machines
nix-build ./build-local.nix -A all && ./result/bin/build-all

# 2. Deploy to all machines
nix-build ./krops.nix -A all && ./result

Customization

Add a new machine:

1. Create directories: machine-specific/machine3/env/ and machine-specific/machine3/images/
2. Add .env file and images for machine3
3. Create config/machine3/configuration.nix
4. Add machine3 to build-local.nix and krops.nix

Update environment variables:

Edit .env in machine-specific/{machine-name}/env/.env, then rebuild locally

Update images:

Replace files in machine-specific/{machine-name}/images/, then rebuild locally

Update web-app code:

Edit files in web-app/, then rebuild locally

After any changes: rebuild locally, then redeploy.