AlexandrAI AGENTS.md
agents-md

Local Link Kr Deploy Agent Guide

Project-specific AGENTS.md guidance for the Local Link Kr deploy scaffold, Docker Compose environments, secret rendering, SMTP checks, tunnel scripts, and suite boundary.

AGENTS.md

Guidance for coding agents working on Local Link Kr Deploy, the deployment scaffold for the Local Link Kr suite.

Project Overview

The deploy repo wires the sibling server, web, admin, and mobile projects into development and production Docker Compose environments. It owns Compose files, image build scripts, rendered environment files, nginx routing, tunnel integration, and database/runtime secret boundaries.

Key paths:

  • compose.development.yml, compose.production.yml: core Docker environments.
  • compose.cloudflare.development.yml, compose.cloudflare.production.yml: tunnel-aware variants.
  • scripts/build-images.sh: builds server, web, mobile, and admin images.
  • scripts/render-env.sh: renders environment files from templates.
  • scripts/check-email-env.sh: validates SMTP source env and redacts password output.
  • scripts/deploy-compose.sh: validates and runs Compose files.
  • scripts/cloudflare-tunnel.sh: manages tunnel setup/run flow.
  • scripts/integration-cloudflare.sh: validates public frontend to API routing.
  • env/*.example: tracked templates only.

Setup Commands

bashcd <project-root>/deploy
docker compose -f compose.development.yml up --build
docker compose -f compose.production.yml up --build
TARGET_ENV=development scripts/check-email-env.sh
TARGET_ENV=development scripts/deploy-compose.sh compose.development.yml
TARGET_ENV=development scripts/integration-cloudflare.sh

Use placeholders such as <WEB_ORIGIN>, <API_ORIGIN>, <POSTGRES_URL>, and <SMTP_PASSWORD> in docs and examples.

Deployment Rules

  • Keep server, web, mobile, and admin deployable independently.
  • Shared behavior belongs in HTTP contracts, generated clients, or documentation, not runtime imports.
  • Production secrets are local deployment inputs, not tracked files.
  • PostgreSQL is required for the server runtime in every environment.
  • Do not publish or hardcode host ports, private hosts, tunnel hostnames, or real credentials in public docs.

Verification

  • Validate rendered env before Compose startup when auth or email flows changed.
  • Run the integration script when routing, nginx, tunnel, or public API path behavior changes.
  • Run the mobile live-data test from the mobile repo only after the development stack is intentionally running.

Security

  • Do not commit local SMTP files, production secret files, database passwords, tunnel credentials, or broad copied environment files.
  • Check scripts must report only redacted credential presence.
  • Keep admin tunnel exposure explicit and protected; do not add public admin ingress as a side effect.