Designing for Ephemerality: Managing State in Scalingo's Container Architecture

The Problem: The Local Disk Trap

Developers transitioning from traditional virtual machines to Scalingo often encounter a critical failure: data loss after a successful deployment or a routine restart. This happens because Scalingo utilizes an ephemeral file system. Any file written to the local container disk is temporary and is wiped clean whenever a new version of the application is deployed or a container is moved to a different host for load balancing.

The key takeaway is that the application container must be treated as a stateless execution engine. All persistent data—user uploads, session state, and database records—must reside outside the container boundary.

Architecture Requirements

To maintain a stable production environment on Scalingo, the architecture must satisfy three primary requirements:

• Immutability: The build phase handled by Cloud Native Buildpacks creates a read-only image. Changes to the runtime environment cannot be persisted back to the image.
• Externalized State: No business-critical data can rely on the local /app or /tmp directories.
• Environment-Driven Configuration: Secrets and API endpoints must be injected via environment variables rather than configuration files bundled in the source code.

The Smallest Suitable Design

For most applications, the simplest compliant design consists of three decoupled components:

1. The Application Stateless: A containerized process, a dyngo, that handles logic and routing.
2. Managed Database: An external PostgreSQL or MySQL instance provided by Scalingo to store structured data.
3. Object Storage: A service like AWS S3 or Google Cloud Storage for files, images, and logs.

By separating compute from state, scaling the application from one instance to ten does not create data silos or synchronization conflicts.

Trust and Data Boundaries

Scalingo enforces a strict boundary between the build environment and the runtime environment. The Buildpack transforms source code into an OCI-compliant image; this process is automated. The developer trusts the Buildpack to resolve dependencies correctly without a manual Dockerfile.

Data boundaries are defined by the network. The application container communicates with the managed database via a secure internal network. The application should never assume it has root access to the underlying host or the ability to modify the container filesystem permanently.

Operational Checks and Verification

To verify that your application is truly stateless and ready for production, perform diagnostic checks.

Testing Ephemerality

Run a command to create a file on the local disk, then trigger a restart via the Scalingo CLI or dashboard. If the file disappears, the system is behaving as expected.

# Run this via the Scalingo CLI to create a dummy file
scalingo run "touch /tmp/persistence_test.txt"

# Verify the file exists
scalingo run "ls /tmp/persistence_test.txt"

# Restart the application to trigger a new container deployment
scalingo restart

# Check again - this should now return a File not found error
scalingo run "ls /tmp/persistence_test.txt"

Risk: Running scalingo restart will cause a brief period of unavailability if you only have one instance running. Perform this in a staging environment first.

Verifying Configuration Injection

Ensure your application is reading from environment variables rather than a .env file bundled in the image.

# Check if a specific variable is present in the environment
scalingo run "printenv DATABASE_URL"

Failure Modes

When the stateless rule is ignored, the following failure modes typically occur:

• The Ghost File Bug: A developer uploads a profile picture that works during testing. After a deployment, pictures are missing because files were stored in /public/uploads on the local disk.
• Session Fragmentation: Using in-memory session storage causes users to be logged out randomly as the load balancer routes them to different container instances.
• Buildpack Conflicts: Because Buildpacks automate the environment, a missing version constraint in package.json or requirements.txt may result in a different dependency version being installed during build than what was used locally.

Conditions for Design Change

The stateless architecture is sufficient for most web applications. Reconsider this design if:

• High-Performance Local Caching: If your app requires multi-gigabyte datasets for rapid lookup that cannot be moved to Redis, you may need to investigate specialized storage volumes or move to a different infrastructure tier.
• Legacy Binary Requirements: If the application requires specific OS-level binaries that Cloud Native Buildpacks cannot provide, you may need to shift toward a custom image strategy to maintain control over the environment.