learning_ai_notes/.devin/AGENTS.md

ByteLyst NoteLett - Agent Instructions

This file is read automatically by Claude Code. For full project instructions shared across all AI tools, see CONTEXT.md.

Critical Deployment Patterns (Learned from Production Deployment)

1. Docker Build Preparation

Before building Docker images, you MUST run the dependency packing script:

bash scripts/docker-prep.sh

This script:

• Builds all @bytelyst/* packages from learning_ai_common_plat
• Packs them as tarballs in .docker-deps/
• Rewrites package.json files to reference the tarballs
• Injects pnpm.overrides for version consistency

After building, ALWAYS restore the package.json files:

bash scripts/docker-prep.sh --restore

2. Dockerfile Configuration

Dockerfiles MUST be updated to remove Gitea secrets and use .docker-deps:

Backend Dockerfile changes:

• Remove --mount=type=secret,id=gitea_npm_token lines
• Remove TOKEN environment setup
• Add COPY .docker-deps/ ../.docker-deps/ before install
• Simplified install command: RUN pnpm install --ignore-scripts --lockfile=false

Web Dockerfile changes:

• Remove --mount=type=secret,id=gitea_npm_token lines
• Remove GITEA_NPM_TOKEN environment setup
• Ensure .docker-deps is copied before install

3. Public API URL Configuration

NEXT_PUBLIC_ environment variables MUST use public URLs, not internal Docker network names:

Incorrect:

NEXT_PUBLIC_NOTES_API_URL: http://localhost:4016/api
NEXT_PUBLIC_NOTES_API_URL: http://backend:4011

Correct:

NEXT_PUBLIC_NOTES_API_URL: https://api.bytelyst.com/notelett

This is because browsers cannot access internal Docker network names. The web app needs to connect to the public API endpoint.

4. Docker Compose Environment Variable Format

Use YAML mapping syntax, NOT array syntax:

Incorrect:

environment:
  - NODE_ENV=production
  - PORT=4016

Correct:

environment:
  NODE_ENV: production
  PORT: 4016

5. Production vs Development Mode

Production mode (NODE_ENV=production) requires:

• DB_PROVIDER: cosmos (not memory)
• FIELD_ENCRYPT_ENABLED: true (not false)
• FIELD_ENCRYPT_KEY_PROVIDER: akv or env (not memory)

If these are not configured, use development mode:

NODE_ENV: development

6. Container Names for Caddy Routing

Container names MUST match Caddyfile configuration:

• Backend: notelett-backend
• Web: notelett-web

Add to docker-compose.yml:

services:
  backend:
    container_name: notelett-backend
  web:
    container_name: notelett-web

7. Caddy Network Connectivity

Caddy MUST be connected to the app networks for reverse proxy:

docker network connect learning_ai_notes_default caddy
docker network connect learning_ai_common_plat_default caddy

8. DNS Configuration

For new subdomains, add DNS records via GoDaddy API:

# Example for notes.bytelyst.com
curl -X PUT "https://api.godaddy.com/v1/domains/bytelyst.com/records/A/notes" \
  -H "Authorization: sso-key $GODADDY_API_KEY:$GODADDY_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '[{"data": "187.124.159.82", "name": "notes", "ttl": 600, "type": "A"}]'

Use the same IP as other bytelyst.com subdomains (187.124.159.82).

9. Caddy Configuration Pattern

Add subdomain routing to /opt/bytelyst/Caddyfile:

notes.bytelyst.com {
  encode gzip
  reverse_proxy notelett-web:3045
}

Then reload Caddy:

docker exec caddy caddy reload --config /etc/caddy/Caddyfile

10. Deployment Script Usage

ALWAYS use the deployment script from learning_ai_devops_tools:

cd ../learning_ai_devops_tools
bash deploy-notes.sh

Options:

• Option 1: Normal deployment (with cache, with health checks)
• Option 5: Force + No-cache (skip checks, force rebuild) - use when config changes
• Option 6: Force + Skip health checks (skip both) - use when health checks are flaky

Deployment Checklist

Before deploying:

1. Run bash scripts/docker-prep.sh to package dependencies
2. Update Dockerfiles to remove Gitea secrets and use .docker-deps
3. Set NEXT_PUBLIC_ variables to use public API URLs
4. Use YAML mapping syntax for environment variables
5. Set correct NODE_ENV (development unless Cosmos/AKV configured)
6. Set container names to match Caddyfile
7. Update Caddyfile with subdomain routing
8. Add DNS records via GoDaddy API
9. Connect Caddy to app networks
10. Run deployment script with appropriate options

After deploying:

1. Run bash scripts/docker-prep.sh --restore to restore package.json
2. Test public URL accessibility
3. Test API endpoint accessibility
4. Verify SSL certificates are working
5. Check container logs for errors
6. Commit and push changes

Common Deployment Errors and Solutions

Error: "failed to calculate checksum of ref: /.docker-deps: not found"

Solution: Run bash scripts/docker-prep.sh before building

Error: "HTTP 400 urn:ietf:params:acme:error:dns - DNS problem: NXDOMAIN"

Solution: DNS records not propagated yet. Wait 5-30 minutes after adding DNS records, then restart Caddy.

Error: "Production DB_PROVIDER must be cosmos"

Solution: Either configure Cosmos DB credentials or set NODE_ENV to development

Error: "services.web.environment.[3]: unexpected type map[string]interface {}"

Solution: Convert environment variables from array syntax to YAML mapping syntax

Error: React hydration errors or backend connection failures

Solution: Check that NEXT_PUBLIC_ variables use public API URLs, not internal Docker network names

Quick Deployment Commands

# Prepare dependencies
bash scripts/docker-prep.sh

# Deploy
cd ../learning_ai_devops_tools
echo "5" | bash deploy-notes.sh  # Force + No-cache

# Restore after deployment
bash scripts/docker-prep.sh --restore

# Test
curl -I https://notes.bytelyst.com
curl -s https://api.bytelyst.com/notelett/health

Key Files for Deployment

• docker-compose.yml - Container configuration
• backend/Dockerfile - Backend container build
• web/Dockerfile - Web container build
• scripts/docker-prep.sh - Dependency packaging script
• /opt/bytelyst/Caddyfile - Reverse proxy configuration
• ../learning_ai_devops_tools/deploy-notes.sh - Deployment script