padreug
70c6c244a4
Enhanced the DEPLOYMENT-GUIDE.md by adding clarity to the steps for adding new machines, updating environment variables, images, and web-app code. Adjusted formatting for better readability. In krops.nix, updated the target hostname for machine1 to 'root@cathare-node' and changed the Nixpkgs reference from 'nixos-25.05' to '25.05' for consistency. These changes improve the documentation and configuration management for the deployment process.
104 lines
3 KiB
Markdown
104 lines
3 KiB
Markdown
# 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**:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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.
|
|
|