Skip to content

Configuration and running

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 — Mail

.env.example documents every variable the project uses, and .env is its development copy.

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.

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:

presentacion/api/src/app.rs
//! 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.

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");

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).

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].