migrated core_nest to mainroom
This commit is contained in:
buenosairesam
234
mainroom/ctrl/server/README.md
Normal file
234
mainroom/ctrl/server/README.md
Normal file
@@ -0,0 +1,234 @@
|
||||
# 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
|
||||
```
|
||||
Reference in New Issue
Block a user