Before learning how, let us understand why so many teams choose containers for their flag service.

The problem containers solve

Software depends on its surroundings: the operating system, the language runtime, the libraries and the settings. When those surroundings differ between machines, the same software behaves differently. Engineers call this the “works on my machine” problem. A container solves it by bundling the application and its surroundings into one sealed package, called an image, that runs the same way everywhere a container engine is available.

What Flagsmith gains

Flagsmith is built from several parts: a web application programming interface, a dashboard that people use in their browsers, background workers and a database. Running these as containers gives you repeatable setups, fast starts and stops, easy upgrades by swapping one image for another, and simple scaling by running more copies. It also lets you test a new version in a throwaway environment that matches production.

When Docker is a good fit

If Docker has always sounded like jargon, this chapter turns it into a handful of simple ideas.

Image, container and registry

An image is a read-only template: a frozen snapshot of an application and everything it needs. A container is a running instance created from an image. You can start many containers from one image, just as you can bake many loaves from one recipe. A registry is an online library where images are stored and shared. Docker Hub is the best-known public registry, and Flagsmith publishes its images there. Companies also run private registries for their own images.

Tags and versions

Every image in a registry has one or more tags, which are labels that usually indicate a version. A tag such as a version number points to a specific release. A tag such as latest points to whatever is newest at the moment. Latest is convenient for experiments but risky for production, because a restart could silently pull a different version than the one you tested. Careful teams pin an exact version and change it only on purpose.

Volumes: where data survives

A container’s own storage is temporary. When the container is removed, whatever was written inside disappears. A volume is storage kept outside the container so that data survives restarts and replacements. Databases need volumes, or an equivalent, because losing the database means losing every flag.

Networks and ports

Containers talk to each other over virtual networks created by Docker. A port is a numbered doorway on a container. By publishing a port, you connect a doorway on the container to a doorway on the host machine, so that outside traffic can reach it. Containers on the same private network can talk freely without publishing anything to the outside world, which is the safer way to connect an application to its database.

Environment variables

Containers are usually configured through environment variables, which are named settings passed in when the container starts. They let one image behave differently in each environment without rebuilding it. The database address, the secret key and the allowed web addresses are typical examples. Because some settings are secrets, how you store and pass them matters a great deal.

Compose and orchestrators

Running several containers by hand is tedious. Docker Compose lets you describe a group of containers, their networks, their volumes and their settings in one file and start everything together. For larger deployments, an orchestrator such as Kubernetes or a managed container service on a cloud platform runs containers across many machines, restarts failed ones and balances traffic. The ideas in this guide apply to all of them, even though the tools differ.

A Flagsmith installation is a small family of cooperating parts. Knowing each member makes every later decision easier.

The API

The API is the heart of Flagsmith. It receives questions from SDKs, such as “what is the value of this flag for this user?”, and requests from the dashboard and automation, such as “create a new flag.” It reads and writes the database, applies targeting rules and returns answers. It is written as a web application, and it listens on a network port inside its container.

The dashboard

The dashboard is the web page where people manage flags. In the common all-in-one image, the dashboard and the API are packaged together, which makes small deployments simple. Flagsmith has also published separate images for the API and the dashboard for teams who prefer to run and scale them independently. Which images exist and how they are combined can change, so confirm the current options in the documentation.

The database

The database is the permanent memory of the system. It holds organisations, projects, environments, features, segments, users, permissions and the audit log. Flagsmith is commonly run with the PostgreSQL database. A container engine can run a database container for tests and small setups, but production teams often prefer a managed database service or a carefully operated database server, because the database is the one part you can never afford to lose.

The background worker

Some work should not happen while a person waits, such as sending webhooks, writing audit entries and processing analytics. Flagsmith can hand this work to a background processor. In small setups the application handles these jobs itself. In larger ones, you run a dedicated task processor as a separate container so heavy background work never slows down the part that answers flag questions.

The cache and the edge proxy

Two optional parts can improve speed. A cache holds ready answers so the database is asked less often. An edge proxy is a lightweight service that sits near your applications, keeps a copy of the flag data and answers SDK questions quickly, reducing load on the main installation. Flagsmith publishes an edge proxy for this purpose, and it is worth knowing about even if you start without it.

Which image you pull, and which version you pin, is one of the quietest and most important decisions in the whole deployment.

Official images

Flagsmith publishes official images in public registries under its own organisation name. The main image bundles the API and dashboard together, which is the easiest way to start. Other images cover the separate dashboard, the task processor and the edge proxy. Always take images from the official publisher and verify the name carefully, because look-alike images with similar names can exist in public registries.

Pinning versions

For anything beyond a quick experiment, pin a specific version tag instead of using latest. Pinning gives you three benefits. You know exactly what is running. You can reproduce the setup on another machine. And you control when an upgrade happens, because nothing changes until you change the tag. A reasonable routine is to read the release notes, test the new version in a staging environment and only then update the pinned tag in production.

Image digests

Tags can be moved by the publisher. A digest is a long fingerprint that identifies one exact image forever. Security-conscious teams sometimes pin by digest for the strictest guarantee, or copy approved images into their own private registry so that production never depends on a public service being available at deploy time.

Private registries and mirroring

Many companies keep a copy of each approved image in a private registry inside their own cloud account. This protects against a public registry being slow, rate limited or unreachable, lets security teams scan every image before it is used, and ensures the exact bytes you tested are the bytes you run. The small extra effort of mirroring pays for itself the first time a public service has a bad day.

A picture of the whole system shows how the containers, the database and the outside world fit together.

flowchart TB
    U["Users and Dashboard Browsers"] --> P["Reverse Proxy with TLS"]
    S["Application SDKs"] --> P
    P --> A1["Flagsmith Container 1"]
    P --> A2["Flagsmith Container 2"]
    A1 --> DB[("PostgreSQL Database")]
    A2 --> DB
    T["Task Processor Container"] --> DB
    A1 --> Q["Task Queue in Database"]
    A2 --> Q
    Q --> T
    T --> W["Outbound Webhooks"]
    DB --> B["Scheduled Backups"]
    M["Monitoring and Logs"] -.-> A1
    M -.-> A2
    M -.-> T
    M -.-> DB

Walking through the diagram

Traffic enters at the top. People using the dashboard and applications using SDKs both reach a reverse proxy, which is a front door that accepts connections, handles encryption and passes requests along. Behind it, two copies of the Flagsmith container share the work. Both copies talk to the same database, which is the single source of truth. A separate task processor container takes over background jobs, such as sending webhooks to outside services. Backups of the database run on a schedule, and monitoring watches every part.

The dotted lines for monitoring show that observation is not part of the request path. It watches quietly and raises alarms. The solid lines show the path real requests and data take. Notice that only the proxy is exposed to the outside world. The application containers, the task processor and the database sit on private networks where outsiders cannot reach them directly.

The pieces in plain words

A start-up sequence that works the same way every time is a sign of a healthy deployment. Let us follow it step by step.

sequenceDiagram
    participant O as Operator or Orchestrator
    participant D as Database
    participant A as Flagsmith Container
    participant T as Task Processor
    participant P as Reverse Proxy
    O->>D: Start database and wait until healthy
    O->>A: Start application with settings
    A->>D: Connect and check schema version
    alt Database needs updates
        A->>D: Apply database migrations
    else Already up to date
        A->>A: Continue start up
    end
    A->>A: Report healthy on health check
    O->>T: Start task processor
    T->>D: Connect and begin polling for jobs
    O->>P: Start or update proxy routes
    P->>A: Send test request
    A-->>P: Healthy response
    P-->>O: Ready to receive traffic

Reading the sequence

The order matters. The database must be running and healthy before the application starts, because the application needs it immediately. When the application starts, it connects to the database and checks whether the structure of the stored data matches what this version of the software expects. If the structure is out of date, the application applies migrations, which are scripted changes that bring the database structure up to date. Once that is done, the application reports that it is healthy.

The task processor starts next, connects to the same database and begins looking for background jobs. Finally, the reverse proxy sends a test request, receives a healthy answer and begins forwarding real traffic. Orchestrators automate this order through health checks and dependency rules, so no human has to watch the sequence.

Why migrations deserve respect

A migration changes the shape of your most precious data. Most are quick and safe, but some can take time on large tables, and once applied they usually cannot be reversed by simply starting an older image. This is why upgrades must always be preceded by a backup, and why running several new containers at the same instant, each trying to migrate the same database, needs care. Many teams run the migration step once, in a controlled way, before bringing up the new application copies.

The same image behaves differently in each place because of the settings you give it. Getting these right is most of the work.

The kinds of settings

Flagsmith containers are configured mainly through environment variables. You can think of the settings as belonging to a few families. Database settings tell the application where its data lives and how to log in. Security settings include a secret key used to protect sessions and signed data, and a list of web addresses the application is allowed to answer to. Behaviour settings control things like whether registration is open, how background tasks run and how much logging to produce. Integration settings configure email delivery, single sign-on and connections to other services.

The database address

The most important setting is the location and credentials of the database. This is typically given as a single connection address containing the host, port, database name, user and password. Because it contains a password, treat it as a secret. Test it from inside the same network as the container, since a database that is reachable from your laptop may not be reachable from the container.

The secret key

The secret key is a long random value that the application uses to protect login sessions and signed information. It must be unique for each installation, generated with a secure random generator, and kept stable. If you change it casually, existing sessions stop working. If you leak it, an attacker may be able to forge signed data. Never reuse the example value from a tutorial.

Allowed hosts and web addresses

Web applications protect themselves by accepting requests only for web addresses they expect. You tell Flagsmith which hostnames it should answer to. A common cause of mysterious errors on a new deployment is that the address people type into their browser is missing from this list. Similar settings tell the dashboard where the API lives and how links in emails should be built, so a wrong public address leads to broken links.

Where to keep settings

If you remember only one chapter, make it this one. Containers can be replaced in seconds, but the database holds everything you cannot afford to lose.

Containerised database or managed service?

You have two broad options. You can run the database as a container next to Flagsmith, which is simple and perfect for development, demonstrations and small internal tools. Or you can use a database that runs outside your container setup: a managed database service from a cloud provider, or a database server your operations team already maintains. For production, the second option is usually wiser, because those services provide automated backups, replication, patching and failover that you would otherwise build yourself.

Sizing and growth

Flagsmith’s data is small compared with many applications, because flags and configuration are modest in size. The audit log and analytics data can grow steadily over time, so plan for storage growth and watch disk space. The database also handles the reads that happen when SDKs ask for flag values, which is why caching and local evaluation in SDKs help so much. Start with a modest instance, measure, and grow it when the numbers say so.

Connections

Every application container opens connections to the database, and a database can only handle so many at once. If you run many copies of the application, the total number of connections multiplies. Teams use connection pooling, a small service that shares a limited number of database connections among many clients, when they scale out. Keep an eye on the number of open connections as you add containers.

Protecting the database

• Place it on a private network, reachable only from the application and task processor containers.
• Use a strong, unique password and a dedicated database user with only the rights Flagsmith needs.
• Enable encryption of connections and of stored data where the platform offers it.
• Keep the database software patched on a regular schedule.
• Separate production and non-production databases completely.

Containers are shy by default. This chapter explains how to let the right visitors in and keep everyone else out.

Container networks

Docker creates private virtual networks for containers. Containers on the same network can find each other by name, so the application can reach the database by using the database container’s name as its address. Containers on different networks cannot talk unless you connect them. A sensible design uses at least two networks: a front network shared by the proxy and the application, and a back network shared by the application, the task processor and the database. The database is then invisible to the proxy and to the outside world.

Publishing ports

A container’s port is unreachable from the outside until you publish it. Flagsmith’s application listens on a port inside its container. In a well-designed setup, you publish only the proxy’s ports, usually the standard secure web port, and leave everything else unpublished. A frequent beginner mistake is to publish the database port to the whole world for convenience, which invites attacks within hours.

The reverse proxy

A reverse proxy sits in front of your application and does several jobs. It terminates TLS, meaning it handles the encryption certificates so that traffic between users and your service is protected. It forwards requests to healthy application containers and spreads the load among them. It can add security headers, limit request sizes, enforce rate limits and write access logs. Common choices include widely used web servers and dedicated proxies, as well as the load balancers offered by cloud platforms.

Certificates and HTTPS

Always serve Flagsmith over HTTPS. A certificate proves that your server is the one it claims to be and enables encryption. Many teams obtain free certificates from automated certificate authorities and let the proxy renew them on a schedule. Expired certificates are one of the most common causes of sudden outages, so monitor their expiry dates and alert well before they lapse.

Addresses that must agree

Several places need to agree on the public web address: the proxy, the allowed hosts setting in Flagsmith, the setting that tells the dashboard where the API lives, and the address configured in every SDK. When something fails strangely after a change of domain name, the first thing to check is whether all of these still match.

Containers forget everything when they are replaced. Storage is the plan for what must be remembered.

What must persist

Almost everything that matters in a Flagsmith deployment lives in the database. The application containers themselves are meant to be disposable: you can destroy and recreate them at any time without losing anything. So the question of persistence mostly means “how do we protect the database’s files?” Other items worth keeping include your configuration files, your certificates and any exported backups.

Types of storage

Performance and safety of disks

Databases need fast, reliable disks. Slow or shared disks cause slow responses that look like application problems. Put the data on storage with predictable performance, keep generous free space and monitor usage. A database that fills its disk usually stops accepting writes, which stops Flagsmith from saving any change.

Protecting against accidents

The most common cause of data loss in container setups is not a hacker but a person, running a cleanup action that removes volumes along with containers. Protect against this with clear naming, restricted permissions, separate volumes for production and test, and, above all, tested backups. Treat any instruction that says “remove everything including volumes” with great suspicion.

The simplest useful deployment runs everything on one machine. Here is how to think about it, without a single line of code.

What a Compose description contains

A Compose description is a single file that lists the services you want, such as the proxy, the Flagsmith application, the task processor and the database. For each service it states which image and version to use, which settings to pass, which networks to join, which volumes to attach and which ports to publish. It also states dependencies and health checks, so that the database starts first and the application waits for it. With this one file, an entire environment can be started, stopped and recreated with a single instruction.

When single-host is enough

A single host suits development environments, demonstrations, internal tools, small teams and low-risk production uses where a short outage is acceptable. It is easy to understand, easy to back up and cheap. Its limitation is obvious: if the machine fails, everything fails. For anything critical, you will want more than one copy of the application on more than one machine, and a database that can survive failure.

Good habits for a single host

Some jobs should happen quietly in the background. The task processor is the part of the system that does them.

What background work exists

Flagsmith performs several jobs that do not need to finish before a request returns. It sends webhooks to your outside services when flags change. It records audit entries. It processes usage and analytics data. It sends emails. If all of this happened while a person or an SDK waited, every request would be slower and a slow external service could drag everything down.

Two ways to run it

In a simple setup, the application containers process background jobs themselves, in the background of their own processes. This is easy and sufficient for light use. In a larger setup, you run a dedicated task processor as its own container, using the same image started in a different mode. The application then places jobs on a queue stored in the database, and the task processor picks them up. This separates concerns: the web-facing containers stay fast, and the background container can be scaled according to the backlog of work.

What to watch

• The size of the job backlog, because a growing backlog means workers cannot keep up.
• The age of the oldest waiting job, which tells you how late your webhooks and records are.
• Failure counts, because repeated failures suggest a broken external service or a bad configuration.
• Network permissions, because the task processor, not the web container, is the one that calls outward to your webhook receivers.

A flag service can change what your product does within seconds, so protecting it deserves real effort. Here are the layers that matter.

Secure the image

Start with what you run. Pull images only from the official publisher, pin versions, and scan images for known weaknesses before they reach production. Keep a private copy in your own registry and rebuild or update regularly, because images contain operating system components that receive security fixes over time. Remove any image you no longer use.

Run containers with minimal power

Containers should not have more rights than they need. Prefer running processes as an ordinary user instead of the all-powerful administrator account. Make the container’s file system read-only where possible, so an intruder cannot easily modify the software. Drop unneeded capabilities and avoid privileged mode, which gives a container nearly the same power as the host. Never mount the container engine’s control socket into an application container, since that is equivalent to handing over the keys to the whole machine.

Secure the network

Expose only the reverse proxy. Keep the database and workers on private networks. Use a firewall at the host or cloud level as a second layer, and test from outside to verify. Restrict who can reach administrative tools and monitoring dashboards. Where your applications run in the same cloud network, consider keeping SDK traffic on private paths and not on the public internet.

Secure the secrets

Store passwords, keys and tokens in a secrets manager or the secret facilities of your orchestrator. Use different secrets for each environment. Rotate them on a schedule and immediately after any suspected exposure. Never place secrets in images, in shared documents or in chat messages, and take care that logs do not print them.

Secure the people

The Flagsmith dashboard has its own users and roles. Give each person an individual account, use the principle of least privilege so that only a few people can change production, and use single sign-on and multi-factor authentication where your edition supports them. Review the list of users regularly and remove people who have left. Protect the keys that automation uses to call the management interface with the same care as passwords.

Upgrading is where container setups shine and where careless teams get hurt. A calm routine makes it boring, which is exactly what you want.

flowchart TD
    A["Read release notes for the new version"] --> B["Back up the database and verify the backup"]
    B --> C["Deploy the new version in staging with a copy of data"]
    C --> D{"Staging checks pass"}
    D -- No --> E["Stop and investigate or wait for a fix"]
    D -- Yes --> F["Schedule a quiet window for production"]
    F --> G["Run database migrations once in a controlled step"]
    G --> H["Replace application containers gradually"]
    H --> I["Replace task processor"]
    I --> J{"Health and errors normal"}
    J -- Yes --> K["Finish and record the version"]
    J -- No --> L["Roll back images and restore data if needed"]

Reading the flow

The path begins with reading, because release notes tell you about changes that need attention, such as new settings, removed features or heavy migrations. Next comes a backup, and a verified one, since a backup that cannot be restored gives false comfort. The new version is then tried in staging against a copy of realistic data. Only if staging looks healthy do you choose a quiet time for production.

In production, the database migration runs once in a controlled step. Then the application containers are replaced gradually, so some old and some new copies handle traffic during the changeover, and finally the task processor is updated. If health checks and error rates look normal, the upgrade is complete and recorded. If not, you roll back.

Understanding rollbacks

Rolling back containers is easy: you point back to the previous image version and restart. Rolling back the database is not always easy. If the new version changed the structure of the data in a way the old version cannot read, the old containers may fail against the migrated database. This is why a backup taken just before the upgrade is the real rollback tool: restoring it returns both the data and its structure to the earlier state, at the cost of any changes made since. Some releases are designed to be compatible with the previous version for a time, and the release notes tell you when that applies.

Rolling updates and zero downtime

When you run more than one application container behind a proxy, you can replace them one at a time, letting the others serve traffic. This is called a rolling update. Combined with health checks, it allows upgrades with little or no visible interruption. It works best when the new and old versions can safely share the same database for the short overlap, which is a question for the release notes.

A backup you have never restored is only a hope. This chapter turns hope into a plan.

What to back up

The database is the essential item, because it contains every flag, segment, user and audit entry. Also keep your deployment description, your settings with secrets stored safely elsewhere, your certificates or the means to reissue them, and records of which image versions you run. With these, you can rebuild everything else from scratch.

Types of database backup

A logical backup exports the data as a portable set of instructions and is simple, flexible and good for moving between versions or machines. A physical or snapshot backup copies the underlying storage and is quicker for large databases and for restoring to the same kind of system. Many teams use both: regular snapshots for fast recovery and periodic logical exports as an independent safety net. Managed database services typically provide automated snapshots and point-in-time recovery, which lets you restore to a chosen moment.

Two numbers that matter

Recovery point objective is how much recent data you can afford to lose, measured in time. If it is fifteen minutes, backups or log shipping must capture changes at least that often. Recovery time objective is how long you can afford to be down while restoring. If it is one hour, your restoration process must be rehearsed and fast enough to meet that. Write these numbers down, because they decide your backup design and its cost.

Rehearse the restore

Protecting the backups themselves

Backups contain everything that the live database does, so they need the same security. Encrypt them, restrict who can read them, store them in a separate account or location and keep several generations. Consider making some copies immutable, meaning they cannot be altered or deleted for a period, to protect against mistakes and malicious deletion.

You cannot fix what you cannot see. Good observation turns surprises into scheduled work.

Health checks

A health check is a small test that tells the container engine or orchestrator whether a container is working. Flagsmith provides a simple health endpoint that returns a success answer when the application is running. Configure your orchestrator to call it regularly. A failing check can cause the platform to restart the container or stop sending it traffic. Distinguish between a liveness check, which asks “is the process alive?”, and a readiness check, which asks “is it ready to serve requests?”, since a container may be alive but still starting.

Logs

Containers write logs to their standard output, and the engine collects them. In production, send logs to a central place, so that they survive container replacement and can be searched across all copies. Include a clear timestamp, the container name and the severity level. Protect logs from containing secrets or sensitive user data, and decide how long to keep them. Logs are the first thing you read in an incident.

Metrics

Metrics are numbers measured over time. Flagsmith can expose operational metrics that common monitoring tools collect, and you can add measurements from the host, the containers, the proxy and the database. A small set of signals tells most of the story.

Alerts that people trust

Alerts should be few, clear and actionable. If an alert fires often and needs no action, people learn to ignore it, and the one real emergency gets lost. Each alert should say what is wrong, why it matters and what to try first. Route urgent ones to a person on call, and send less urgent ones to a daily review.

When one machine is no longer enough, containers make it natural to grow. Here is how the pieces scale and what tools help.

Scaling the application

The Flagsmith application containers are largely stateless, so scaling them is simple: run more copies behind the proxy or load balancer. Each copy opens connections to the database, so more copies mean more connections, which is the first limit most teams meet. Use connection pooling when the count grows. Set resource limits for memory and processor use on each container, so a misbehaving copy cannot starve its neighbours.

Scaling the database

The database is harder to scale because it holds the state. The usual path is to grow the instance first, then add read replicas to share read traffic, tune indexes and caching, and reduce the load by using smart SDK behaviour. Because the volume of flag changes is small compared with the volume of flag reads, read scaling is more important than write scaling.

Scaling the background work

Add task processor containers when the backlog of jobs keeps growing. Watch for contention on the database as more workers compete for jobs, and tune the number of workers to the work rather than simply adding more.

Orchestrators

An orchestrator is a system that runs containers across many machines, restarts failed ones, balances traffic and performs rolling updates automatically. Kubernetes is the most widely used. Cloud platforms also offer managed container services that hide much of the machinery. Flagsmith provides guidance and packaging for popular orchestrators, which you should read in the current documentation. Orchestrators add power and complexity, so adopt one only when your needs justify it.

High availability means the service keeps working when parts fail. It is a design, not a switch.

flowchart TB
    LB["Load Balancer across Zones"] --> A1["App Container Zone A"]
    LB --> A2["App Container Zone B"]
    LB --> A3["App Container Zone C"]
    A1 --> PG["Database Primary Zone A"]
    A2 --> PG
    A3 --> PG
    PG --> R1["Standby Replica Zone B"]
    PG --> R2["Read Replica Zone C"]
    T1["Task Processor Zone A"] --> PG
    T2["Task Processor Zone B"] --> PG
    PG --> BK["Backups to Separate Account"]
    R1 -. "Automatic failover" .-> PG

Reading the design

The load balancer sits across several availability zones, which are separate data centre areas within a region with independent power and networking. Three application containers, one in each zone, serve traffic, so the loss of an entire zone leaves two still working. Two task processors, in different zones, make sure background work continues. The database has a primary in one zone and a standby in another that can take over automatically if the primary fails. A read replica shares read traffic. Backups go to a separate account, so even a serious mistake in the main account cannot destroy every copy.

The weakest link

The chain is only as strong as its weakest link. A beautiful application layer on top of a single database server is not highly available. Check each part of the chain: load balancer, application, database, storage, network, certificates, secrets and the deployment process itself. Ask of each, “what happens if this fails right now?” and write the answer down.

Do not forget the client side

No design is perfect, so your applications should also protect themselves. Set safe default values in code, let SDKs keep recent answers in memory, prefer local evaluation on servers and use short timeouts. With these habits, even a complete outage of Flagsmith results in your product running with known behaviour, not breaking.

Once Flagsmith is running, your applications must find it. This chapter explains how SDKs connect and how an edge proxy can lighten the load.

Pointing SDKs at your own address

SDKs talk to the hosted Flagsmith service by default. When you run your own deployment, you give each SDK the web address of your installation through a configuration setting that every SDK supports. This single setting is how an application switches between the hosted service and your own containers. Keep the address in your application’s configuration, not scattered in code, so that changing it is a simple, safe edit.

Environment keys

Each environment in Flagsmith has keys that SDKs use to identify which environment they belong to. A client-side key is meant for browsers and mobile apps and is safe to expose, because it only reads flags. A server-side key unlocks more capabilities, such as local evaluation, and must be kept secret on servers. Using the wrong kind of key in the wrong place is a common mistake, so label them clearly.

The edge proxy

The edge proxy is a small, separate service that you run close to your applications. It keeps a copy of the flag data for the environments you choose, refreshes it from the main installation at intervals, and answers SDK questions locally. This reduces the load on the main installation and the database, keeps latency low and lets applications continue to receive answers even if the main installation is briefly unavailable. The trade-off is that its data can be slightly behind the main installation, depending on how often it refreshes, and it adds one more thing to run and monitor.

A deployment you can repeat from a description is far safer than one assembled by hand. This chapter shows how to make deployments routine.

Many environments, one design

Most teams need at least a development setup, a staging setup and a production setup. They should use the same images, the same container descriptions and the same procedures, differing only in settings such as addresses, sizes and secrets. This sameness is the great benefit of containers: what you test in staging is very close to what runs in production.

Infrastructure as code

Infrastructure as code means describing your servers, networks, databases and container settings in files that are stored in version control, instead of clicking through consoles by hand. Changes are reviewed like any other change, and the files can recreate the whole environment on demand. This protects against the dreaded “snowflake” server that nobody can rebuild because its setup lived only in someone’s memory.

Pipelines

A pipeline is an automated sequence that takes a change through steps: check, test, scan, deploy. For Flagsmith, a pipeline might validate the container description, scan the pinned images, deploy to staging, run health checks and tests, and then, after approval, deploy to production with a rolling update. Automation reduces human error and leaves a clear record of what changed and when.

Managing Flagsmith’s own configuration

Beyond the deployment, you may want to keep Flagsmith’s flags and settings under control through automation, using the management interface to create flags in each environment consistently. This helps keep staging and production in step and gives you a repeatable way to rebuild a lost installation.

Most performance gains come from a few simple habits, not from heroic tuning. Here they are in order of usefulness.

First, ask fewer questions

The cheapest request is the one never made. Configure SDKs to cache answers in memory for a short time, to use local evaluation on servers, and to avoid sending identity information on every action. Poll for changes at sensible intervals instead of constantly. These client-side habits often reduce load on the deployment by a large factor.

Then, give containers the right resources

Containers need enough memory and processor time. Too little causes slowness and restarts. Too much wastes money. Set explicit limits and requests based on measurements, and revisit them when traffic changes. Run enough application copies to handle your peak with a margin, since a system running near its limit has no room for a spike.

Next, look after the database

The database is usually the first real bottleneck. Keep it on fast storage, give it enough memory so that common data stays cached, make sure indexes exist where the software expects them, and keep the database software maintained. Watch for slow queries and for the number of open connections. Use pooling when many containers connect.

Put a cache and an edge in front

Where the read load is heavy, caching and the edge proxy can absorb most of it. They trade a small amount of freshness for a large reduction in database work.

Measure before and after

When something goes wrong, follow the path of a request from the outside in. Most problems fall into a handful of familiar groups.

Common symptoms and likely causes

Teams that run containers for years settle on the same few habits that work, and fall into the same few traps.

Patterns that work

Anti-patterns to avoid

A compact checklist of habits that pay off, and mistakes that cause pain.

Protecting against the single expert problem

A self-managed deployment often begins as one person’s project. The risk is obvious: when that person leaves or is unavailable, the knowledge leaves with them. Share the on-call duty, keep the setup written down in version control, rehearse recovery with different team members and keep a short runbook where everyone can find it.

Protecting against drift

Over time, hand-made changes make environments differ from their descriptions, which is called drift. Avoid it by making all changes through the version-controlled files and the pipeline, and by periodically comparing the running system with the description. A deployment that can be rebuilt from its description is a deployment you can trust.

Let us follow an imaginary team as it grows its Flagsmith deployment in three stages, so you can see the ideas in a real-feeling sequence.

The team

Imagine a company called Harbourline that makes scheduling software for clinics. It has twenty-five engineers, a website, a mobile app and an internal operations group of three people. The product team wants gradual rollouts and quick kill switches. Because customer data is sensitive and a few clinics ask where their data lives, the company decides to self-host Flagsmith using containers.

Stage one: the laptop

A developer first runs Flagsmith on a laptop using a single container description that starts the application and a database container. Within an hour, the team sees the dashboard, creates a flag and connects a test application. The lesson at this stage is understanding, not durability. Nobody worries about backups, because the data is disposable. The developer writes down every setting used and which image version was pulled.

Stage two: a shared staging server

Next, the team sets up a staging environment on a small cloud machine. They keep the container description in version control, pin exact image versions, put a reverse proxy with an HTTPS certificate in front, and move secrets into the cloud’s secret storage. The database moves to a managed service with automatic backups, and the staging environment gets its own network. The team runs one backup restore as a drill and discovers a missing permission, which they fix. They also add health checks and a basic dashboard of request rate, errors and database connections.

Stage three: production

For production, the operations group builds on the staging design. Three application containers run across two availability zones behind a load balancer. A dedicated task processor runs in each zone. The managed database has a standby copy in a second zone and backups copied to a separate account. A mirrored, scanned copy of each image lives in the company’s private registry. An edge proxy runs in the same network as the application servers, so server code receives flag answers within a millisecond or two. A pipeline deploys changes: staging first, then production through a rolling update after approval.

flowchart LR
    A["Stage 1: Laptop with one description and a test database"] --> B["Stage 2: Staging server with proxy, HTTPS, managed database and secrets"]
    B --> C["Stage 3: Production in two zones with load balancer and standby database"]
    C --> D["Stage 4: Edge proxy, pipeline, drills and quarterly reviews"]
    B -.-> E["Lesson: backups need a restore drill"]
    C -.-> F["Lesson: monitor the task processor"]
    D -.-> G["Lesson: upgrade in small regular steps"]

Reading the picture

The solid line shows the growth of the deployment. The dotted lines show the lessons learned at each stage. Notice that complexity was added only when the need appeared. The laptop needed understanding, staging needed repeatability and security, and production needed redundancy and discipline. At no point did the team build for a scale it did not have.

What happened on a bad day

Before you declare a deployment ready for real traffic, walk through this checklist honestly. Each unchecked line is a small risk you have agreed to carry.

Images and configuration

• Every image is from the official publisher, pinned to an exact version and mirrored privately.
• Images have been scanned and the results reviewed.
• All settings are in version-controlled files, and all secrets are in a secrets manager.
• The public address, allowed hosts and dashboard-to-API settings all agree.

Data

• The database is managed or carefully operated, on a private network, with encryption enabled.
• Automated backups run, are copied off-site and are encrypted.
• A restore has been rehearsed recently, and the time taken is recorded.
• Recovery point and recovery time targets are written down and met.

Network and security

• Only the reverse proxy is public, with a valid certificate and automatic renewal.
• Containers run as normal users with minimal privileges, and none mount the engine’s control socket.
• Dashboard users have individual accounts, least-privilege roles and multi-factor authentication where available.
• Automation keys are stored safely and have a rotation plan.

Operations

• Health checks exist for every container.
• Logs go to a central place with sensible retention.
• Alerts cover errors, latency, restarts, disk space, database connections, task backlog, certificates and backups.
• A runbook exists, and at least two people can follow it.
• An upgrade procedure has been tested in staging.

Application side

• Every flag read has a safe default value in code.
• SDKs use caching and, on servers, local evaluation.
• The service address is a single configuration setting.
• A test has shown how the product behaves when Flagsmith is unreachable.

Containers have been used in production for years by many well-known companies. Their experience offers lessons that apply directly to a Flagsmith deployment.

Every important word used in this guide, in plain language, for quick lookup.

Short answers to the questions people ask most often when deploying Flagsmith in containers.

Everything in this guide comes down to a handful of ideas you can carry into your next deployment.

Docker turns Flagsmith from a pile of installation steps into a repeatable package. The application, dashboard, task processor and edge proxy are disposable containers. The database is the precious part. A sound deployment puts a reverse proxy at the only public door, keeps everything else on private networks, pins and mirrors its images, stores secrets safely, monitors every component and practises its backups and upgrades. It grows in stages, only as far as the need requires, and it leaves your applications able to carry on even when the flag service cannot answer.