Understanding application instances

4 min read Updated 1 month ago

Understanding application instances

What is an instance?

An instance is a running copy of your application. When you deploy your application, you can choose to run multiple instances simultaneously to improve availability and handle more traffic. Each instance runs the same code but operates independently.

Think of instances like having multiple cashiers at a store - they all do the same job, but having more than one means you can serve more customers and if one takes a break, the others keep working.

How multiple instances work

Shared resources

When running multiple instances, certain resources are shared between all instances:

  • Database connections - All instances connect to the same database
  • Persistent storage - Files stored in persistent volumes are accessible by all instances
  • Environment variables - Configuration settings are identical across instances
  • Custom volume mounts - Any custom storage you've configured is shared

Instance independence

Each instance operates independently in these ways:

  • Memory and CPU - Each instance has its own allocated resources
  • Temporary files - Files not stored in persistent volumes are separate per instance
  • Process state - Running processes and in-memory data are isolated
  • Log output - Each instance generates its own logs

Instance lifecycle

Disposable by design

Important: Any instance can be terminated and recreated at any time. This happens during:

  • Application deployments and updates
  • System maintenance
  • Automatic scaling operations
  • Instance health check failures
  • Resource constraints

Zero-downtime updates

When updating your application, the platform uses a rolling update strategy:

  1. New instances are created with the updated code
  2. Traffic gradually shifts to the new instances
  3. Old instances are terminated once new ones are healthy
  4. At least one instance remains available throughout the process

Building applications for multiple instances

Data storage guidelines

Use persistent storage for:

  • User uploads and files - Store in persistent volumes or external storage
  • Application data - Use database services (MySQL, PostgreSQL, MongoDB)
  • Session data - Store in Redis or database, not in-memory
  • Cache data - Use Redis or Valkey services for shared caching
  • Configuration files - Use persistent volumes for files that need to persist

Avoid storing in instance memory:

  • User session information
  • Temporary files you need to keep
  • Application state that other instances need
  • File uploads or user-generated content

Application design best practices

Stateless design:

  • Don't rely on files stored locally in the instance
  • Don't assume the same instance will handle consecutive requests
  • Store all important data in databases or persistent volumes
  • Make sure your application can start quickly and cleanly

Health checks:

  • Implement health check endpoints that respond within 5 seconds
  • Ensure your application is ready to serve traffic quickly after startup
  • Handle database connection failures gracefully

Background jobs:

  • Use separate worker instances for long-running tasks
  • Make jobs resumable in case instances restart
  • Store job progress in databases, not instance memory

When to use multiple instances

Benefits of multiple instances

  • Higher availability - If one instance fails, others continue serving requests
  • Better performance - Distribute load across multiple instances
  • Zero-downtime deployments - Updates happen without service interruption
  • Improved reliability - Reduced impact from individual instance issues

Cost considerations

Each additional instance increases your costs proportionally. For example:

  • 1 instance = base cost
  • 2 instances = 2× base cost
  • 3 instances = 3× base cost

Managing your instances

Monitoring instance health

You can monitor your instances through the Debug tab, which shows:

  • Total number of instances
  • Running instances
  • Pending instances (starting up)
  • Failed instances
  • Detailed status information

Scaling your application

You can adjust the number of instances (1-10) through the Resources tab. Changes take effect on your next deployment.

Common pitfalls to avoid

File storage issues:

  • Don't save uploaded files to the local filesystem unless using persistent volumes
  • Don't assume files created by one instance will be visible to others
  • Use database services or persistent volumes for shared file storage

Session management:

  • Don't store user sessions in instance memory
  • Use database sessions or Redis for session storage
  • Ensure sessions work across different instances

Application state:

  • Don't rely on global variables or static data between requests
  • Don't assume the application will always use the same instance
  • Design your application to be completely stateless

Summary

Multiple instances provide better availability and performance for your application, but require careful design to ensure your application works correctly when any instance can be terminated and recreated at any time. Store all important data in databases or persistent volumes, design your application to be stateless, and implement proper health checks for the best experience.