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

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
# 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:

```bash
# 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
```bash
sudo nginx -t
# Fix errors in server/nginx/core_nest.conf
```

### Services won't start
```bash
cd ~/core_nest/ctrl
./logs.sh              # Check all logs
./logs.sh amar         # Check specific service
docker ps -a           # See all containers
```

### Database issues
```bash
# 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.

```bash
# 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.

```bash
# 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:

```bash
# 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:
  ```bash
  docker exec core_nest_db pg_dump -U postgres amarback > backup.sql
  ```