krops-multi-deploy/DEPLOYMENT-GUIDE.md

Web-App Deployment Guide

Overview

This setup allows each machine to build the web-app with its own specific configuration:

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

Structure

.
├── web-app/                          # Shared web-app source code
│   ├── package.json
│   ├── index.html
│   └── public/                       # Images will be copied here during build
├── 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-helper.nix                  # Build script available on target machines

How It Works

1. Krops Deployment (krops.nix)

When you deploy with krops, it copies to each target machine:

• web-app → /var/src/web-app (shared source code)
• machine-specific/{name}/env/.env → /var/src/web-app-env (machine-specific .env)
• machine-specific/{name}/images/ → /var/src/web-app-images/ (machine-specific images)

2. Building on Target Machine

After deployment, SSH into the target machine and run:

build-web-app

This script:

1. Copies the machine-specific .env file to the web-app directory
2. Copies the machine-specific images to web-app/public/
3. Runs npm run build to build the web-app

The build output will be in /var/src/web-app/dist/

Usage

Deploy to a single machine:

nix-build ./krops.nix -A machine1 && ./result

Deploy to all machines:

nix-build ./krops.nix -A all && ./result

Build the web-app on target machine:

ssh root@machine1.example.com
build-web-app

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 target in krops.nix

Update environment variables:

Edit the appropriate .env file in machine-specific/{machine-name}/env/.env

Update images:

Replace files in machine-specific/{machine-name}/images/

After making changes, redeploy with krops.