soleprint/mainroom/ctrl/server/README.md

Server Configuration

Everything that runs on the server (not locally).

Purpose

This directory contains server-side scripts and configs that get deployed to AWS. Separate from ctrl/ which contains local orchestration scripts.

Structure

server/
├── setup.sh              # Idempotent server setup (run on AWS)
├── nginx/
│   └── core_nest.conf    # Single nginx config for all services
└── scripts/              # Any other server-side scripts

Expected Server Structure

When deployed, the AWS instance should look like:

~/core_nest/              # This repo (deployed via deploy.sh)
├── server/               # Server-side scripts
│   ├── setup.sh          # Run this first
│   └── nginx/
├── ctrl/                 # Local scripts (work remotely too)
│   ├── build.sh, start.sh, stop.sh, logs.sh, status.sh
│   └── manual_sync/
├── amar/
│   ├── docker-compose.yml
│   ├── .env              # Production values
│   ├── Dockerfile.*
│   ├── init-db/
│   └── src/              # Synced from local via manual_sync/
│       ├── back/         # Django source
│       └── front/        # Next.js source
└── pawprint/
    ├── docker-compose.yml
    ├── .env              # Production values
    └── (bare metal or src/ depending on deployment)

Usage

First-Time Server Setup

# 1. From local machine: Deploy files
cd ~/wdir/ama/core_nest/ctrl
./deploy.sh

# 2. SSH to server
ssh mariano@mcrn.ar

# 3. Run server setup (idempotent - safe to re-run)
cd ~/core_nest/server
./setup.sh

This will:

• Ensure directory structure exists
• Install Docker, Docker Compose, Nginx, Certbot
• Check SSL certificates (prompts if missing)
• Install nginx config
• Create .env files from examples

Updates/Changes

# From local: edit server/nginx/core_nest.conf or server/setup.sh
# Then deploy:
./deploy.sh

# On server: re-run setup to apply changes
ssh mariano@mcrn.ar 'cd ~/core_nest/server && ./setup.sh'

Build and Start Services

# On server (or via SSH):
cd ~/core_nest/ctrl
./build.sh              # Build all images
./start.sh -d           # Start detached
./status.sh             # Check status

Key Files

server/setup.sh

Idempotent setup script that runs on AWS:

• Checks/installs: Docker, Nginx, Certbot
• Verifies SSL certs exist
• Installs nginx config
• Creates .env files from examples

Safe to run multiple times - won't break existing setup.

server/nginx/core_nest.conf

Single nginx config file for all services:

• amar.nest.mcrn.ar (frontend + backend)
• pawprint.mcrn.ar
• artery.mcrn.ar
• album.mcrn.ar
• ward.mcrn.ar

Edit this file locally, deploy, re-run setup.sh to apply.

Environment Variables

Create production .env files:

# On server:
nano ~/core_nest/amar/.env       # Set INIT_DB_SEED=test or prod
nano ~/core_nest/pawprint/.env   # Set NEST_NAME, ports, etc.

SSL Certificates

Certificates are managed via Let's Encrypt:

# Wildcard for *.nest.mcrn.ar (for amar)
sudo certbot certonly --manual --preferred-challenges dns -d '*.nest.mcrn.ar'

# Wildcard for *.mcrn.ar (for pawprint services)
sudo certbot certonly --manual --preferred-challenges dns -d '*.mcrn.ar'

Auto-renewal is handled by certbot systemd timer.

Troubleshooting

Nginx config test fails

sudo nginx -t
# Fix errors in server/nginx/core_nest.conf

Services won't start

cd ~/core_nest/ctrl
./logs.sh              # Check all logs
./logs.sh amar         # Check specific service
docker ps -a           # See all containers

Database issues

# Check which seed data is configured
grep INIT_DB_SEED ~/core_nest/amar/.env

# Rebuild database (WARNING: deletes data)
cd ~/core_nest
docker compose -f amar/docker-compose.yml down -v
./ctrl/start.sh amar -d

Test Directory Symlinking

setup-symlinks.sh

Purpose: Create symlinks to share test directories across services on the same filesystem.

This allows ward/tester to access tests from amar_django_back_contracts without duplication.

# Preview changes
ssh mariano@mcrn.ar 'cd ~/core_nest/ctrl/server && ./setup-symlinks.sh --dry-run'

# Apply changes
ssh mariano@mcrn.ar 'cd ~/core_nest/ctrl/server && ./setup-symlinks.sh'

What it does:

• Creates symlinks from pawprint/src/ward/tools/tester/tests/ to amar/src/back/tests/contracts/
• Symlinks each domain directory (mascotas, productos, solicitudes, workflows)
• Symlinks shared utilities (endpoints.py, helpers.py, base.py, conftest.py)

Benefits:

• Single source of truth for tests
• No duplication
• Tests automatically sync when backend is deployed
• Works across Docker containers sharing the same filesystem

Alternative: If symlinks don't work (different filesystems, Windows hosts), use ../ctrl/sync-tests.sh to copy test files.

sync-tests.sh (in ctrl/ directory)

Purpose: Sync test files as an alternative to symlinks.

# From local machine - sync to Docker
./ctrl/sync-tests.sh

# From local machine - sync to bare metal
./ctrl/sync-tests.sh --to-bare-metal

Use this when:

• Symlinks are not supported
• Services are on different filesystems
• You need independent test copies

Verification

After setup, verify symlinks are working:

# Check symlinks exist
ssh mariano@mcrn.ar 'ls -lah ~/core_nest/pawprint/src/ward/tools/tester/tests'

# Verify they point to correct location
ssh mariano@mcrn.ar 'readlink ~/core_nest/pawprint/src/ward/tools/tester/tests/mascotas'

# Test in browser
open https://ward.mcrn.ar/tools/tester/

Security Notes

• Never commit production .env files
• SSL certs in /etc/letsencrypt/ (not in repo)
• Database volumes persist in Docker volumes
• Backup database regularly:

  docker exec core_nest_db pg_dump -U postgres amarback > backup.sql