Docker Deployment
Relevant source files
The following files were used as context for generating this wiki page:
Docker Deployment in the Loco framework is designed to provide a streamlined, "batteries-included" experience for containerizing Rust applications. By leveraging built-in generators, developers can automatically produce production-ready Dockerfile and .dockerignore configurations tailored to their specific project structure, including support for static asset serving and database dependencies.
The deployment process follows the principle of "Convention Over Configuration," allowing a solo developer to move from a local development environment to a containerized production environment with minimal manual intervention. The generated artifacts are optimized for the Rust ecosystem, typically focusing on release builds and efficient layer caching.
Sources: README.md:28-30, docs-site/config.toml:139-142, docs-site/content/blog/deploy-aws.md:41-45
Automated Deployment Generation
Loco provides a dedicated CLI command to scaffold deployment artifacts. This generator interacts with the developer to determine the target environment and automatically detects project features like static assets.
The Generation Workflow
When the generation command is executed, Loco creates two primary files in the project root:
- Dockerfile: A multi-stage build file (typically) that handles the compilation of the Rust binary and the final execution environment.
- .dockerignore: A configuration to prevent unnecessary files (like
target/ornode_modules/) from being sent to the Docker daemon, significantly reducing build times.
The diagram shows the internal CLI flow when generating deployment files, including the automatic detection of static assets.
Sources: docs-site/content/blog/deploy-aws.md:47-56, docs-site/content/blog/frontend-website.md:144-154, snipdoc.yml:109-116
Deployment CLI Commands
| Command | Description |
|---|---|
cargo loco generate deployment | Interactive prompt to select deployment type (Docker, Nginx, etc.). |
cargo loco generate deployment docker | Directly generates Docker-specific artifacts. |
Sources: snipdoc.yml:109-116, docs-site/content/blog/deploy-aws.md:47-50
Building and Running Containers
Once the artifacts are generated, standard Docker CLI tools are used to build and execute the application. Loco applications are designed to respect environment variables for configuration.
Container Build and Execution Flow
This sequence demonstrates the transition from a local build to a running containerized service.
Sources: docs-site/content/blog/deploy-aws.md:58-69, docs-site/content/blog/frontend-website.md:156-166
Environment Configuration
Containers typically require the LOCO_ENV environment variable to be set to production to ensure the application loads the correct configuration from config/production.yaml. The default listening port for the server is 5150.
# Running the container with production environment
docker run -e LOCO_ENV=production -p 5150:5150 myapp start
Sources: docs-site/content/blog/frontend-website.md:166, docs-site/content/blog/deploy-aws.md:113-115
Dependency Services in Docker
For local development or specialized testing, Loco provides standard commands to run required infrastructure components like PostgreSQL and Redis using Docker.
| Service | Docker Command | Default Port |
|---|---|---|
| PostgreSQL | docker run -d -p 5432:5432 -e POSTGRES_USER=loco -e POSTGRES_PASSWORD="loco" postgres:15.3-alpine | 5432 |
| Redis | docker run -p 6379:6379 -d redis redis-server | 6379 |
Sources: snipdoc.yml:50-59
Infrastructure Integration (AWS Fargate)
Loco's Docker images are compatible with modern container orchestration services. A common pattern involves pushing the generated image to Amazon Elastic Container Registry (ECR) and deploying via AWS Fargate.
AWS Deployment Pipeline
- Build: Create the image locally via the generated
Dockerfile. - Tag: Prepare the image with the ECR repository URI.
- Push: Upload the image to ECR.
- Execute: Define an ECS Task Definition that references the ECR image and specifies the
startcommand.
The diagram illustrates the flow from code to a high-availability cloud environment using containerized Loco.
Sources: docs-site/content/blog/deploy-aws.md:86-120
ECS Task Definition Requirements
When configuring container definitions for Loco in Docker, certain parameters are standard:
- Command:
["start"](to initiate the Loco server). - Port Mapping: Container port
5150. - Health Check: Endpoint
/_health(typically matched with HTTP 200/202).
Sources: docs-site/content/blog/deploy-aws.md:113-118, docs-site/content/blog/deploy-aws.md:188-192
Multi-Frontend Considerations
Loco's Docker generation is "frontend-aware." If a project contains a frontend/ directory (e.g., React or Angular), the generator includes logic to ensure static assets are built and included in the final image.
- Vite/React: Loco detects the static assets and includes them as part of the image.
- Angular: Requires adjustment of the
staticmiddleware path inconfig/production.yamlto match the Angular build output (e.g.,frontend/dist/frontend/browser) before building the container.
Sources: docs-site/content/blog/frontend-website.md:154, docs-site/content/blog/angular-frontend.md:73-81
Conclusion
Docker Deployment in Loco transforms a Rust application into a portable, scalable unit of execution. By automating the creation of the Dockerfile and providing standard patterns for environment configuration and service dependencies, Loco ensures that the deployment phase is as productive as the development phase. Whether running a single container locally or orchestrating a fleet on AWS Fargate, the framework maintains a consistent interface for application startup and health monitoring.