Scaling

Hubfly Space supports two practical scaling workflows for containerized applications: vertical auto-scale and manual replicas. Vertical auto-scale adjusts CPU and memory within limits you define. Manual replicas create additional containers from an existing container and can optionally place them behind a load balancer for horizontal traffic distribution.

Use this page when you need to choose between scaling up one container, creating multiple replicas, adding load balancing, or preparing a production scaling plan for APIs, workers, dashboards, and stateful services.

Overview

Scaling is the process of giving an application more capacity when load increases and reducing operational waste when load is low. In Hubfly, scaling is designed around container resources, runtime behavior, replicas, and load balancer routing.

Hubfly scaling has two main user-facing models:

Vertical scaling changes the size of a container. Replica scaling changes how many containers exist. Production systems often use both: vertical auto-scale for per-container headroom and manual replicas behind a load balancer for traffic distribution.

Use Cases

Use vertical auto-scale when one container needs flexible CPU or memory headroom. This is useful for APIs with bursty traffic, dashboards with occasional heavy requests, workers with variable job sizes, and applications where adding more replicas would not immediately help.

Use manual replicas when the application can run multiple identical copies. This is the normal pattern for stateless web apps, public APIs, background workers, and services that can safely process traffic or jobs from several containers.

Use manual replicas with a load balancer when public HTTP traffic should be spread across several backend containers behind one domain.

Use internal replicas when you want additional same-app containers without creating or updating a public load balancer. This can be useful for private workers, internal services, or cases where routing is handled separately.

Avoid replica scaling for stateful databases unless the database is explicitly designed for clustering or replication. PostgreSQL, MySQL, Redis, queues, and object stores require workload-specific scaling patterns.

Architecture And Workflow Overview

A production scaling workflow usually looks like this:

1. Identify the bottleneck: CPU, memory, storage, network, database, queue depth, or request concurrency.
2. Decide whether the workload needs a larger container or more containers.
3. For vertical scaling, enable auto-scale and set base and maximum CPU/RAM limits.
4. For replica scaling, use Replicate to create one or more additional containers.
5. If replicas serve public traffic, place them behind a load balancer.
6. Keep internal dependencies private and scale them separately.
7. Monitor logs, metrics, endpoint health, and billing after the change.
8. Remove unused replicas or lower limits when demand changes.

The key operational difference is that vertical auto-scale keeps one container identity, while replicas create additional containers that must be routed, monitored, billed, and operated as separate runtime units.

Requirements

Before scaling a production workload, prepare:

• A container running in a project
• A clear understanding of the bottleneck
• Baseline CPU and RAM values
• Maximum CPU and RAM values for vertical auto-scale
• A safe port for replica traffic when using load balancing
• A health check path for load-balanced replicas
• A rollback plan if the new size or replicas behave incorrectly
• Application support for multiple instances if using replicas

For load-balanced replicas, the application should bind to 0.0.0.0, listen on the configured port, and behave safely when multiple containers receive traffic.

Vertical Auto-Scale

Vertical auto-scale automatically adjusts CPU and memory capacity for one container within limits you set. You define a base allocation and maximum allocation. Hubfly registers the container with the vertical scaling service using those min and max limits.

Vertical auto-scale uses:

• Base CPU as the minimum CPU
• Base RAM as the minimum memory
• Max CPU as the upper CPU limit
• Max RAM as the upper memory limit

A valid vertical auto-scale configuration requires the maximum values to be greater than or equal to the base values.

Base CPU: 1 vCPU
Max CPU: 4 vCPU
Base RAM: 1024 MB
Max RAM: 4096 MB
Scale mode: Vertical

This configuration lets the container run at the base size and grow toward the maximum limits when the workload requires more CPU or memory.

When To Use Vertical Auto-Scale

Use vertical auto-scale for:

• APIs with occasional CPU bursts
• Admin dashboards with inconsistent load
• Workers with variable job size
• Applications that are hard to split across replicas
• Services that need more memory during peak usage
• Workloads where one process benefits from more CPU or RAM

Vertical auto-scale is a good first option when the application is not yet ready for multiple replicas or when one larger process is simpler than several smaller ones.

Vertical Auto-Scale Limits

The base resource values are the floor. The max resource values are the ceiling.

If base resources are too low, the app may still struggle before scaling catches up. If max resources are too high, costs and noisy workload behavior can become harder to predict. Choose limits that reflect realistic production demand.

Recommended starting pattern:

Base CPU: normal steady-state need
Base RAM: memory needed to run safely at idle or average load
Max CPU: peak burst allowance
Max RAM: peak memory allowance with headroom

For memory-heavy services, set max RAM carefully. A memory leak can consume the available ceiling and still fail later. Auto-scale helps with legitimate peaks; it does not fix application memory leaks.

Manual Replicas

Manual replicas create additional containers from an existing container. A replica copies the existing container configuration into a new deployment so the application can run as another instance.

Hubfly supports two replica workflows:

Manual replicas are explicit. Hubfly does not automatically create or destroy horizontal replicas based on traffic today. You choose how many additional replicas to create.

Independent Replicas

An independent replica creates a standalone copy of the container. It does not automatically join a load balancer and does not change the original container’s public routing.

Use independent replicas for:

• Creating a copy for testing
• Reproducing a production issue in the same project
• Preparing a replacement container
• Running a temporary variant of an existing service
• Creating a separate worker or internal service from the same image

Independent replicas should be reviewed after creation. Confirm environment variables, ports, volumes, runtime settings, and networking behavior before using the replica for production traffic.

Scale Replicas

Scale replicas create multiple same-app containers. When load balancing is enabled, Hubfly can add the new replicas to an existing load balancer group or create a new load balancer group for them.

Scale replica options include:

• Additional replica count
• App port
• Target weight
• Load balancing algorithm
• Internal replicas toggle

Replica count must be between 1 and 20 for a single operation.

Additional replicas: 3
App port: 3000
Load balancing: round_robin
Target weight: 1
Internal replicas: false

If the source container is already in one load balancer group, new scale replicas are added to that existing group. If the source container is not already in a group and internal replicas are disabled, Hubfly creates a new load balancer group and a managed hubfly.app domain for the replicas.

If the source container belongs to multiple load balancer groups, add replicas from the specific load balancer context instead of using the generic container replicate flow.

Internal Replicas

Internal replicas create same-app replicas without setting up or updating a load balancer. Internal mode skips port, algorithm, and weight configuration.

Use internal replicas when:

• The replicas do not need public traffic
• The service is a worker or background process
• Traffic is routed by another system
• You want extra containers for private project networking
• You need additional capacity without a public domain change

Internal replicas can share the original app naming behavior for internal networking. Treat them as additional runtime units that still need monitoring, billing awareness, and operational cleanup.

Load-Balanced Replicas

Load-balanced replicas are the recommended approach for horizontally scaling public web apps and APIs.

When scaling behind a load balancer:

• Choose the app port that receives traffic
• Choose or reuse a balancing algorithm
• Set target weights
• Keep backend versions compatible
• Verify health checks and logs after scaling

Available algorithms are:

For production, combine replicas with a load balancer and a health check path such as /health or /ready.

Vertical Auto-Scale vs Manual Replicas

Use vertical auto-scale when a single container needs more headroom. Use manual replicas when the workload can be split across multiple containers.

Setup Steps

Enable Vertical Auto-Scale

1. Open the container resource or advanced settings.
2. Enable Auto-Scale.
3. Select Vertical scale mode.
4. Set the base CPU and RAM.
5. Set Max CPU and Max RAM.
6. Confirm max values are greater than or equal to base values.
7. Save the container settings.
8. Monitor CPU, memory, application latency, and cost after enabling.

Create An Independent Replica

1. Open the source container.
2. Select Replicate.
3. Choose Independent replica.
4. Create the replica.
5. Open the new container.
6. Review environment variables, ports, volumes, and runtime settings.
7. Add endpoints or domains only if the replica should receive traffic.

Create Load-Balanced Scale Replicas

1. Open the source container.
2. Select Replicate.
3. Choose Scale replica.
4. Set Additional Replicas.
5. Confirm the app port.
6. Choose the load balancing algorithm if a new group will be created.
7. Set target weight.
8. Create replicas.
9. Confirm the load balancer group and managed domain or existing group.
10. Test traffic and monitor target health.

Create Internal Replicas

1. Open the source container.
2. Select Replicate.
3. Choose Scale replica.
4. Enable Internal Replicas.
5. Set the number of additional replicas.
6. Create replicas.
7. Confirm they are running and connected to the project network.
8. Monitor logs and resource usage.

Deployment Examples

Bursty API With Vertical Auto-Scale

Workload: Public API
Base CPU: 1 vCPU
Max CPU: 4 vCPU
Base RAM: 1024 MB
Max RAM: 4096 MB
Scale mode: Vertical
Public routing: Single HTTP endpoint or custom domain

Use this when traffic spikes require more resources but the app does not yet need multiple replicas.

Stateless API With Manual Replicas

Workload: API replicas
Source container: api
Additional replicas: 2
App port: 3000
Load balancer: enabled
Algorithm: round_robin
Target weight: 1
Domain: api.example.com

Use this when request concurrency is the bottleneck and the API can safely run multiple instances.

Worker Pool With Internal Replicas

Workload: Queue workers
Source container: worker
Additional replicas: 5
Internal replicas: enabled
Public endpoint: none
Load balancer: none

Use this when workers pull jobs from a queue and do not need public HTTP routing.

Larger Single Database Container

Workload: PostgreSQL
Scaling model: Vertical resource increase
Replica model: Avoid manual app replicas unless using database-native replication
Storage: High Performance volume

Use vertical sizing for database capacity, but do not clone database containers as generic app replicas unless the database architecture supports it.

CI/CD Integration

Scaling should be part of release planning, not only incident response.

For vertical auto-scale:

• Set base and max resources before expected traffic increases
• Watch memory and CPU after each release
• Review whether new code changes require higher limits
• Keep max limits aligned with budget expectations

For manual replicas:

• Deploy the new image first
• Add replicas gradually
• Put public replicas behind a load balancer
• Use health checks before shifting traffic
• Remove old or temporary replicas after rollout

A safe rollout pattern is:

1. Build and test the new image.
2. Deploy one new container.
3. Add it to a load balancer with a low weight.
4. Watch logs, health checks, and latency.
5. Increase traffic or add more replicas.
6. Remove stale replicas after validation.

Docker And Compose Usage

For Docker image deployments, replicas should use the same image tag or a deliberately chosen new image tag. Immutable tags make rollout and rollback easier.

For Compose stacks, scale at the service role level. Web, API, worker, database, and cache services should not all be scaled the same way.

Common Compose scaling pattern:

api: manual replicas behind load balancer
worker: internal replicas
postgres: vertical resources + High Performance storage
redis: vertical resources or Redis-specific topology

Do not treat a Compose database service like a stateless web service. Databases need database-aware replication and backup workflows.

Networking Considerations

Manual replicas that receive public traffic should use a load balancer. The load balancer gives one domain for multiple backend containers and supports algorithms such as round_robin, least_conn, and ip_hash.

Internal replicas should stay on the private project network unless they intentionally need public endpoints.

When creating replicas, confirm the app port. The port must match the process inside each replica. If the app listens on 3000, use port 3000 for the load balancer target.

If replicas use sessions, uploads, or local disk, make sure the application can handle multiple instances. Use shared storage, external sessions, or object storage where needed.

Security Best Practices

Do not create public endpoints for every replica. Put replicas behind a load balancer when they serve the same public app.

Keep databases and queues private. Use HubTunnels for administrative access instead of public exposure.

Avoid cloning stateful services blindly. Replicating a database container does not automatically create safe database replication.

Review environment variables and secrets on replicas. Replicas inherit configuration patterns, so a bad secret or wrong endpoint can be copied into multiple containers.

Remove temporary replicas when they are no longer needed. Unused containers still create operational and billing surface area.

Scaling Considerations

Vertical auto-scale helps with per-container saturation. Manual replicas help with throughput and availability for horizontally safe workloads.

Scale the bottleneck. If the database is overloaded, adding API replicas may make the problem worse. If the API is CPU-bound, vertical auto-scale or more API replicas can help. If queue depth is growing, internal worker replicas may help.

Replicas work best for stateless services. If the app stores session state, files, or cache locally, move that state to a shared dependency before relying on replicas.

Billing follows resources you keep active. More replicas mean more containers. Higher vertical limits can increase cost during heavy usage.

Performance Notes

Vertical auto-scale can give a process more CPU and memory headroom, but it does not fix slow queries, inefficient code, memory leaks, or external API bottlenecks.

Manual replicas improve concurrency only if the workload can be divided. Replicas do not help if every request waits on the same overloaded database.

Workers are often easier to scale horizontally than web apps because each worker can pull jobs independently from a queue.

Load balancers distribute traffic, but target health and application readiness still matter. Use health checks for production replicas.

Monitoring And Logging

Monitor scaling changes from several angles:

• CPU usage
• Memory usage
• Container restarts
• Request latency
• Error rates
• Queue depth
• Worker throughput
• Load balancer target health
• Traffic distribution between replicas
• Database and cache pressure
• Billing after scaling changes

For replicas, logs should make it easy to identify which container handled a request or job. Include request IDs, job IDs, and service names in application logs.

Troubleshooting

Auto-Scale Cannot Be Enabled

Check that max CPU and max RAM are set and greater than or equal to the base CPU and RAM. Vertical auto-scale requires valid min and max limits.

Container Still Feels Slow After Vertical Auto-Scale

The bottleneck may be database latency, external API calls, storage, network, or application code. Check logs and metrics before raising limits again.

Replica Creation Fails

Check project permissions, source container configuration, image availability, registry credentials, environment variables, volume mounts, and region health.

Replicas Are Created But Do Not Receive Traffic

Check whether they were created as internal replicas. If public traffic should reach them, add them to a load balancer and verify the target port.

Load Balancer Sends Traffic To The Wrong Port

Confirm the app port in the replicate flow. The load balancer target port must match the port where the replica listens.

Sessions Break Across Replicas

The app may store session state locally. Use shared session storage such as Redis or a database, or use load balancer stickiness only when it fits the application.

Adding API Replicas Makes Things Worse

The shared dependency may be overloaded. Check database, Redis, object storage, or external API limits before adding more app replicas.

Common Errors

Best Practices

Start by identifying the bottleneck before scaling.

Use vertical auto-scale for CPU and memory headroom on one container.

Use manual replicas for stateless APIs, web apps, and workers.

Use load balancers for public app replicas.

Use internal replicas for private workers and non-public services.

Keep databases, queues, and caches private.

Make jobs idempotent before scaling workers.

Use immutable image tags for production replicas.

Monitor cost after adding replicas or increasing max limits.

Remove unused replicas after traffic spikes, tests, or rollouts.

Production Recommendations

For production APIs, combine replicas with a load balancer, SSL, force SSL, and a real health check path.

For bursty single-process apps, enable vertical auto-scale with realistic max CPU and RAM limits.

For workers, use internal replicas and monitor queue depth, job duration, and duplicate-processing safety.

For databases, prefer vertical sizing, storage performance tuning, backups, and database-native replication strategies instead of generic container replicas.

For rollouts, create replicas gradually, monitor them, then shift traffic through the load balancer.

Limitations

Vertical auto-scale is the active automatic scaling model for CPU and memory.

Horizontal automatic scaling is not the same as manual replicas. Today, horizontal capacity is created explicitly through the Replicate flow.

Manual replicas are not automatically removed when traffic drops.

Replicas are separate containers and can increase cost.

Replica scaling assumes the application can safely run multiple instances.

Load-balanced scaling does not solve stateful database replication or shared-storage design.

FAQ

What Is Vertical Auto-Scale?

Vertical auto-scale adjusts CPU and memory for one container within the base and maximum limits you configure.

What Are Manual Replicas?

Manual replicas are additional containers created from an existing container. They can be standalone, internal-only, or added behind a load balancer.

Is Horizontal Auto-Scale Automatic Today?

No. Horizontal capacity is managed through manual replicas today. You choose how many replicas to create.

When Should I Use A Load Balancer?

Use a load balancer when multiple replicas should receive public traffic behind one domain.

Can I Create Internal Replicas Without A Load Balancer?

Yes. Enable Internal Replicas in the scale replica flow to create same-app replicas without load balancer setup.

How Many Replicas Can I Create At Once?

The scale replica flow allows 1 to 20 additional replicas per operation.

Should I Replicate A Database Container?

Usually no. Databases require database-aware replication, backups, failover, and consistency planning. Use vertical scaling and proper database architecture instead.

Real-World Examples

Public API Scaling

Start with vertical auto-scale for base headroom. When request concurrency grows, create two or more API replicas and place them behind a load balancer with round_robin or least_conn.

Queue Worker Scaling

Create internal worker replicas when queue depth grows. Keep workers private, monitor duplicate job behavior, and scale down by removing replicas after the backlog clears.

Admin Dashboard Scaling

Use vertical auto-scale for occasional heavy dashboard queries. If the dashboard becomes public and high-traffic, add replicas behind a load balancer and move sessions to shared storage.

Production Rollout With Replicas

Create a replica with the new image version, add it to a load balancer at a low weight, monitor logs and metrics, then increase traffic or add more replicas after validation.

Related Docs

• Platform
• Load Balancers
• Networking
• Compose
• Volumes
• Deploy From Image
• Deploy From Git