# Flagsmith self-hosted: running the open source feature flag platform in Docker

> Flagsmith is a BSD-3-Clause feature flag and remote config platform that ships a Docker Compose file for self-hosting. The quick start is short, but the compose file's defaults are development settings you must replace before production.

**Flagsmith/flagsmith** — Flagsmith is an open-source feature flag platform with remote config, experimentation, and self-hosted or cloud deployment options.

- Repository: https://github.com/Flagsmith/flagsmith
- Website: https://www.flagsmith.com
- Stars: 6,558 · Forks: 568
- Language: Python
- License: BSD-3-Clause
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/flagsmith-flagsmith

## What Flagsmith actually solves, and for whom

The problem is deployment coupling. A feature that is finished in code but not ready for every user still has to ship with the release, so teams either hold the release or accept that the code is live and dark. Flagsmith separates the two: you wrap a section of code with a flag, and the flag's state is decided at runtime for an environment, a user or a segment. The README describes the same idea in one line: "Just wrap a section of code with a flag, and then use Flagsmith to toggle that feature on or off for different environments, users or user segments."

The audience is teams that want that control without handing the decision surface to a vendor. The repository is public under BSD-3-Clause, the deployment path is a Compose file you run yourself, and the README states that on-premise and private cloud hosting are supported. The same repository also carries a hosted SaaS option at flagsmith.com, so the project is not asking you to choose between open source and a managed service; it is offering both from one codebase.

Segments are the part that makes it more than a switchboard. A segment is a rule over user attributes, and the README lists A/B and multivariate testing on top of that, plus organisation, project and role management for teams. If all you need is one boolean read from a config file, the platform is heavier than the problem.

## How the platform is put together

The repository is a monorepo, and the top level tells you most of the architecture: api/ holds the Django application, frontend/ holds the React UI, sdk/ holds client libraries, docs/ holds documentation, and infrastructure/ plus the deployment descriptors (fly.toml, render.yaml, docker-compose.yml) cover hosting. openapi.yaml sits at the root, which is the contract the API exposes and the SDKs consume.

The data path is conventional for this class of tool. The API stores flag definitions, environments, segments and identities in Postgres; the compose file points DATABASE_URL at postgresql://postgres:password@postgres:5432/flagsmith. SDKs do not query Postgres. They fetch an environment document from the API and evaluate flags locally, which is what keeps flag evaluation off the critical path of a request.

Analytics are a separate concern, and the compose file makes a deliberate choice there: USE_POSTGRES_FOR_ANALYTICS is set to 'true' with the comment "Store API and Flag Analytics data in Postgres". That keeps a small deployment to one database instead of adding an analytics store, at the cost of putting analytics write volume on the same Postgres instance that serves flag configuration. The Dockerfile comments also show the project builds several distinct images from one file: an open source API image, an open source frontend image, a unified image, and separate SaaS and private cloud targets. The unified image is the default target, which is why a single compose service can serve both the API and the UI.

## Installing Flagsmith with Docker Compose

The README's quick start is two commands. The first downloads the compose file from the main branch, the second starts the stack.

```bash
curl -o docker-compose.yml https://raw.githubusercontent.com/Flagsmith/flagsmith/main/docker-compose.yml
docker-compose -f docker-compose.yml up
```

What you should see is a bootstrapped admin user, organisation and project. The README shows the log line to look for:

```txt
Superuser "admin@example.com" created successfully.
Please go to the following page and choose a password: http://localhost:8000/password-reset/confirm/.../...
```

Open that link, set a password, and you are in the UI on port 8000. The compose file sets FLAGSMITH_DOMAIN to localhost:8000 and DJANGO_ALLOWED_HOSTS to '*', which is what makes the local URL work out of the box.

Before you point anything real at it, edit the environment block. Three values in the file are explicitly labelled as needing a change: DJANGO_ALLOWED_HOSTS, FLAGSMITH_DOMAIN and DJANGO_SECRET_KEY, each carrying the comment "Change this in production". The database password in DATABASE_URL is the literal string password. The compose file also leaves PREVENT_SIGNUP and ALLOW_REGISTRATION_WITHOUT_INVITE commented out, with a note that uncommenting and setting the latter to false restricts signups to invitations only. On a public host, that is the difference between an internal tool and an open registration page.

For a first real flag, create a project and an environment in the UI, add a flag, and read it from an SDK. The repository ships an sdk/ directory and the README names TypeScript, .NET and Java among "15+ popular languages", so pick the client for your stack and use the environment key the UI gives you.

## Where the defaults stop being good enough

The Compose file is a demo, and it says so. ENVIRONMENT is set to production, but DJANGO_ALLOWED_HOSTS is '*' and the secret key is the word "secret". Those two lines together mean the stack is configured to answer on any Host header while signing with a value that is public in the repository. Running it on a reachable address without changing both is the main way a self-hosted Flagsmith becomes someone else's Flagsmith.

Task handling is the second thing to look at. The compose file sets TASK_RUN_METHOD to TASK_PROCESSOR and notes the alternatives: SYNCHRONOUSLY and SEPARATE_THREAD, the latter being the default. The choice matters when flag changes or analytics writes are frequent, because the wrong mode moves work into the request path. The README does not document which mode fits which load, so this is a setting to test against your own traffic rather than assume.

Licensing is the third boundary. The README is direct that "Enterprise-level governance and management features are available with a valid Flagsmith Enterprise license" and points to a version comparison page. If your requirements include those governance features, the open source deployment is not the whole product, and the comparison page is the document that tells you where the line falls. The README does not enumerate which features are on which side.

The wrong-tool case is simpler. If your flags change once a quarter, a table in your own database and a config reload will do the same job with none of the moving parts. Flagsmith earns its keep when flags change often, when non-engineers need to change them, or when you need per-segment targeting and A/B measurement.

## Flagsmith compared with Unleash

The comparison people reach for is Unleash, and the difference is in what the two projects treat as the centre of the system. Flagsmith's compose file is a complete product stack: Postgres, the Django API, the React frontend and the task processor, with the unified image serving API and UI together. The README frames the product around three named capabilities, feature flags, remote config and A/B testing, and lists integrations and organisation management alongside them. The repository layout backs that up: there is a frontend/ directory, an infrastructure/ directory and deployment descriptors for Fly.io and Render, not just a server.

Unleash is also an open source feature flag server with a UI and SDKs, so the two overlap heavily on the core loop of defining a flag and evaluating it in a client. The practical difference for an adopter is the shape of the self-hosted deployment and the extension surface you inherit. Flagsmith's own openapi.yaml and sdk/ directory mean the API contract and the clients are versioned in the same repository as the server, which makes it easier to check whether the SDK you depend on matches the server you run.

That is a difference in packaging and release discipline, not a claim that one evaluates flags faster. The README makes no performance claims for either, and none should be inferred from the repository structure.

## Maintenance, releases and what the licence lets you do

The last push to the repository was on 2026-09-10, and the most recent release in the same window is v2.271.1, dated 2026-09-10, with v2.271.0 on 2026-09-09 and v2.270.0 on 2026-09-07. Three releases in four days is a fast cadence, and it sets the upgrade cost: if you track the project, you are tracking a moving version number. The repository contains release-please-config.json and .release-please-manifest.json at the top level, which is the automation behind that numbering, and a CHANGELOG.md for the record.

For a self-hosted deployment the upgrade path is the image, and the Dockerfile is where the variants live. The comments list the shippable targets: oss-api, oss-frontend, oss-unified, saas-api, private-cloud-api and private-cloud-unified. A Compose deployment uses the unified image, so an upgrade means pulling a new tag and restarting, with a database migration implied by the Django API. The README does not document rollback, and the compose file has no migration step of its own, so the safe assumption is that you own the backup and the downgrade decision.

On licence, the README states the majority of the platform is BSD-3-Clause and that a small number of repositories are MIT. BSD-3-Clause is permissive: it allows commercial use and modification with the licence and copyright notice retained. The enterprise features sit under a separate commercial license, and the README points to the version comparison page rather than listing them. Whether that boundary affects you is a question for your own legal review, not something the repository answers.

## Conclusion

Adopt Flagsmith if you need feature flags and remote config that run on your own infrastructure under BSD-3-Clause, and you are willing to harden the Compose defaults before anyone outside your laptop reaches the API. Do not adopt it if you want a managed service with no operational surface, or if you need the enterprise governance features the README places behind a separate commercial license. Verify three things first: that postgres, the API and the frontend all come up from the compose file on your host, that you have replaced DJANGO_SECRET_KEY, DJANGO_ALLOWED_HOSTS, FLAGSMITH_DOMAIN and the database password, and that the SDK for your language is published and current enough for your stack.

## FAQ

### What does Flagsmith do?

It is a feature flag and remote config platform. You wrap a section of code with a flag, then toggle it on or off for different environments, users or user segments without deploying new code.

### Is Flagsmith open source?

Yes. The README states the majority of the platform is open source under the BSD-3-Clause license, with a small number of repositories under MIT. Enterprise governance and management features require a separate Flagsmith Enterprise license.

### how to use flagsmith

Download the Compose file, run docker-compose up, and use the password reset link printed in the logs to set the bootstrapped admin password. After that, create a project and environment in the UI, add a flag, and read it from one of the SDKs in the sdk/ directory.

### Is there a free feature flag service available?

The README says the hosted version can be tried for free at flagsmith.com, and the open source deployment can be self-hosted at no licence cost under BSD-3-Clause. Enterprise-level governance features are not part of that free tier.

### flagsmith vs launchdarkly

The repository supports a self-hosted deployment through its Docker Compose file and publishes the platform under BSD-3-Clause, which is the main structural difference from a closed hosted service. The README does not compare Flagsmith with LaunchDarkly feature by feature.

### flagsmith vs growthbook

The README lists A/B and multivariate testing and segments as built-in capabilities of Flagsmith, alongside feature flags and remote config. The repository does not contain a comparison with GrowthBook, so any difference beyond that is not documented here.

## Sources

- [Flagsmith/flagsmith on GitHub](https://github.com/Flagsmith/flagsmith)
- [License: BSD-3-Clause](https://github.com/Flagsmith/flagsmith/blob/main/LICENSE)
- [Project website](https://www.flagsmith.com)
- [README](https://github.com/Flagsmith/flagsmith/blob/main/README.md)
- [Releases](https://github.com/Flagsmith/flagsmith/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/flagsmith-flagsmith