Configuration and running
Environment
Section titled “Environment”Configuration is read once at startup, from the environment and from .env (a variable already
set wins). A value that is set but invalid stops the server with a message. It never falls back
to a default: a typo in SERVICE_PORT would otherwise start the server on a port nobody routes
to.
| Variable | Default | |
|---|---|---|
SERVICE_PORT |
8080 |
the port the API listens on |
CORS_ALLOWED_ORIGINS |
any origin | comma-separated; .env lists the dev servers |
RUST_LOG |
info |
the tracing filter |
PUERTO_BANNER |
true |
false hides the startup banner |
DATABASE_URL |
— | --db projects |
WORKER_PORT and the worker’s variables |
8081 |
Running more than one worker |
AUTH_* |
— | Authentication |
SMTP_URL, MAIL_FROM |
— |
.env.example documents every variable the project uses, and .env is its development copy.
What the server gives you
Section titled “What the server gives you”presentacion/api/src/main.rs is four lines: it reads Config and hands bootstrap.rs’s routes
to puerto-web’s App, which serves:
| Path | |
|---|---|
/api/… |
the API |
/ |
the Swagger UI |
/health |
liveness: 200 ok while the process answers |
/health/ready |
readiness: 200 ready, or 503 when a dependency does not answer (SELECT 1 with --db) |
On Ctrl-C or SIGTERM it stops accepting connections and gives in-flight requests 8 seconds to
finish, below docker stop’s default of 10
(ADR-0008). A failure at
startup, such as a database that is down, is an error message and exit code 1, never a panic.
Your own middleware and routes
Section titled “Your own middleware and routes”presentacion/api/src/app.rs is written once by puerto nuevo and never touched again.
generado/bootstrap.rs hands it every route, the API, the Swagger UI and the health probes, last:
//! Lo escribe una vez `puerto nuevo`; desde entonces es tuyo y ningún generador vuelve a tocarlo.//!//! `generado/bootstrap.rs` entrega todas las rutas —la API, la Swagger UI, las sondas de salud— a//! `configurar`, lo último. Añade aquí middleware (`rutas.with(…)`) o rutas propias//! (`rutas.at(…)`).
use poem::{Endpoint, Route};
pub fn configurar(rutas: Route) -> impl Endpoint { rutas}Add middleware with rutas.with(…) and routes of your own with rutas.at(…).
Rate limiting, request ids, a webhook endpoint outside the OpenAPI service: they go here, and
regenerating bootstrap.rs never loses them.
Logging
Section titled “Logging”Plain tracing, with no logger to inject
(ADR-0006). Every request
is logged with its method, path, status and duration, and every use case logs inicio and fin
with its id. Never log the params or a request body: they are user data.
tracing::info!(id = %producto.id, "cambiar_precio_producto: fin");The toolchain
Section titled “The toolchain”rust-toolchain.toml pins Rust 1.95.0 with rustfmt and clippy, and every crate uses
edition 2024. Clippy gains lints between releases, so pinning is what makes make lint answer the
same on every machine and in CI. Bump it on purpose, then fix what the new clippy reports
(ADR-0009).
IDE snippets
Section titled “IDE snippets”puerto nuevo writes snippets for Zed (.zed/snippets/, loaded automatically) and VS Code
(.vscode/*.code-snippets). Neovim with LuaSnip can load the VS Code ones:
require("luasnip.loaders.from_vscode").lazy_load({ paths = { "./.vscode" } })They follow the generator’s own shapes: domain-model, repository-trait, app-use-case,
uow-write, poem-endpoint-action, poem-response-enum, poem-route-test, consumer-arm,
object-mother, sqlx-test, vo-enum and more for Rust; migration-create-table,
migration-unique-index and sql-soft-delete for SQL; web-container, web-repo-method,
web-form-field and web-route for the frontend. The prefixes are English; what they write
follows the project’s Spanish names (deberia_…_cuando_…, // Preparar, ejecutar…). Rewrite
them with puerto generar snippets [--ide zed|vscode].