From d083335ab1399ba658d0765a7157cc9f32dcbe1f Mon Sep 17 00:00:00 2001 From: wadii Date: Fri, 16 Oct 2026 11:25:30 +0200 Subject: [PATCH 1/4] docs: document the dashboard's first-run admin setup for self-hosted --- README.md | 7 +-- .../using-the-django-admin.md | 4 +- .../environment-variables.md | 3 +- .../core-configuration/initial-setup.md | 59 +++++++++++++++---- .../hosting-guides/docker.md | 9 +-- frontend/README.md | 7 +-- 6 files changed, 57 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index 7ce7dd333143..c10c87a8c75e 100644 --- a/README.md +++ b/README.md @@ -44,12 +44,7 @@ curl -o docker-compose.yml https://raw.githubusercontent.com/Flagsmith/flagsmith docker-compose -f docker-compose.yml up ``` -The application will bootstrap an admin user, organisation, and project for you (learn more about Flagsmith terminology in our [data model docs](https://docs.flagsmith.com/flagsmith-concepts/data-model)). You'll find a link to set your password in your Compose logs: - -```txt -Superuser "admin@example.com" created successfully. -Please go to the following page and choose a password: http://localhost:8000/password-reset/confirm/.../... -``` +Once the containers are up, open [http://localhost:8000](http://localhost:8000). On a fresh install, the dashboard walks you through creating your admin account and your first organisation (learn more about Flagsmith terminology in our [data model docs](https://docs.flagsmith.com/flagsmith-concepts/data-model)). ## Check a feature flag in your code diff --git a/docs/docs/deployment-self-hosting/administration-and-maintenance/using-the-django-admin.md b/docs/docs/deployment-self-hosting/administration-and-maintenance/using-the-django-admin.md index 6c04373ed4db..cb797e71932c 100644 --- a/docs/docs/deployment-self-hosting/administration-and-maintenance/using-the-django-admin.md +++ b/docs/docs/deployment-self-hosting/administration-and-maintenance/using-the-django-admin.md @@ -24,8 +24,8 @@ A user with [`is_superuser`](https://docs.djangoproject.com/en/4.2/ref/contrib/a You can obtain a user with these permissions using any of these methods: -* Use the [`createsuperuser` management command](/deployment-self-hosting/core-configuration/initial-setup#local-installation) from a Flagsmith API shell. -* If no users exist yet, [visit the Initialise Config page](/deployment-self-hosting/core-configuration/initial-setup#cloud-environments-eg-heroku-ecs). +* Use the [`createsuperuser` management command](/deployment-self-hosting/core-configuration/initial-setup#from-the-command-line) from a Flagsmith API shell. +* If no users exist yet, [create the first account from the dashboard](/deployment-self-hosting/core-configuration/initial-setup#from-the-dashboard-recommended). * Manually set the `is_staff` and `is_superuser` database fields for your user in the `users_ffadminuser` table. ## Authentication diff --git a/docs/docs/deployment-self-hosting/core-configuration/environment-variables.md b/docs/docs/deployment-self-hosting/core-configuration/environment-variables.md index f87dd5f94f89..f8ec93a0eca6 100644 --- a/docs/docs/deployment-self-hosting/core-configuration/environment-variables.md +++ b/docs/docs/deployment-self-hosting/core-configuration/environment-variables.md @@ -33,7 +33,8 @@ relevant section below for more details. set, no logs will be stored. If set to `-`, the logs will be sent to `stdout`. - `DJANGO_SETTINGS_MODULE`: Python path to settings file for the given environment, e.g. "app.settings.develop" - `ALLOW_ADMIN_INITIATION_VIA_CLI`: Enables the `bootstrap` management command which creates default admin user, - organisation, and project. + organisation, and project. `bootstrap` runs on startup with `migrate-and-serve` only; see + [Initial Setup](/deployment-self-hosting/core-configuration/initial-setup#automatically-on-startup). - `ADMIN_EMAIL`: Email to use for the default superuser creation. - `ORGANISATION_NAME`: Organisation name to use for the default organisation. - `PROJECT_NAME`: Project name to use for the default project. diff --git a/docs/docs/deployment-self-hosting/core-configuration/initial-setup.md b/docs/docs/deployment-self-hosting/core-configuration/initial-setup.md index 11b4731c61f2..bfa68feaf236 100644 --- a/docs/docs/deployment-self-hosting/core-configuration/initial-setup.md +++ b/docs/docs/deployment-self-hosting/core-configuration/initial-setup.md @@ -1,28 +1,61 @@ --- -title: "Initial Setup" -description: "How to initialise the instance and create the first superuser." +title: 'Initial Setup' +description: 'How to initialise the instance and create the first superuser.' sidebar_position: 10 --- -The application is built using Django which comes with a handy set of admin pages available at `/admin/`. To access these, you'll need to create a superuser. This user can also be used to access the admin pages or the application itself if you have the frontend application running as well. This user can be created using the instructions below, depending on your installation: +A new Flagsmith instance has no users. The first account you create is a superuser: it can manage the instance and sign +in to the Django Admin at `/admin/`. Pick one of the options below, depending on your installation. -## Local Installation +## From the dashboard (recommended) + +Open the dashboard, e.g. [http://localhost:8000](http://localhost:8000) if you are running our +[Docker Compose file](/deployment-self-hosting/hosting-guides/docker). While the instance has no users, the dashboard +shows a **Welcome to Flagsmith** screen instead of the login page. Select **Get Started**, enter your name, email and +password, then name your first organisation. + +Nothing is printed to the logs for this step. Once the first account exists, the dashboard shows the usual login and +sign-up pages. + +## From the command line + +From a running Flagsmith container: + +```bash +flagsmith createsuperuser +``` + +For a local installation from source: ```bash cd api python manage.py createsuperuser ``` -## Cloud Environments (e.g. Heroku, ECS) +## Automatically on startup + +Set `ALLOW_ADMIN_INITIATION_VIA_CLI` to `true` to let the `bootstrap` command create a superuser (`ADMIN_EMAIL`), an +organisation (`ORGANISATION_NAME`) and a project (`PROJECT_NAME`). Each step is skipped if a user, organisation or +project already exists. + +`bootstrap` runs automatically only when the container starts with `migrate-and-serve`. If you run `migrate` and `serve` +as separate containers, as our Docker Compose file does, run `flagsmith bootstrap` yourself once migrations have +finished. It prints a link to set the superuser's password: + +```txt +Superuser "admin@example.com" created successfully. +Please go to the following page and choose a password: http://localhost:8000/password-reset/confirm/.../... +``` + +## Without the dashboard -Once the app has been deployed, you can initialise your installation by accessing `/api/v1/users/config/init/`. This will show a page with a basic form to set up some initial data for the platform. Each of the parameters in the form are described below. +If you only run the API, you can initialise your installation by visiting `/api/v1/users/config/init/`. This page shows +a basic form; submitting it creates the superuser and returns a link to set its password. -| Parameter name | Description | -| --------------- | -------------------------------------------------------------------------------------------------------------------------------- | -| Username | A unique username to give the installation superuser | -| Email | The email address to give the installation superuser | -| Password | The password to give the installation superuser | -| Site name | A human-readable name for the site, e.g. 'Flagsmith' | +| Parameter name | Description | +| --------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| Email | The email address to give the installation superuser | +| Site name | A human-readable name for the site, e.g. 'Flagsmith' | | Site domain[^1] | The domain that the frontend of the site will be running on, e.g. app.flagsmith.com. This will be used for e.g. password reset emails. | -[^1]: It is important that this is correct as it is used in the password reset emails to construct the reset link. \ No newline at end of file +[^1]: It is important that this is correct as it is used in the password reset emails to construct the reset link. diff --git a/docs/docs/deployment-self-hosting/hosting-guides/docker.md b/docs/docs/deployment-self-hosting/hosting-guides/docker.md index 4010f66ed928..0621571c8d88 100644 --- a/docs/docs/deployment-self-hosting/hosting-guides/docker.md +++ b/docs/docs/deployment-self-hosting/hosting-guides/docker.md @@ -14,7 +14,9 @@ curl -o docker-compose.yml https://raw.githubusercontent.com/Flagsmith/flagsmith docker-compose -f docker-compose.yml up ``` -Wait for the images to download and run, then visit `http://localhost:8000/`. As a first step, you will need to create a new account at [http://localhost:8000/signup](http://localhost:8000/signup) +Wait for the images to download and run, then visit [http://localhost:8000](http://localhost:8000). On a fresh install, the dashboard shows a **Welcome to Flagsmith** screen: select **Get Started** to create your admin account and your first organisation. Nothing is printed to the Compose logs for this step. + +This first account is a superuser. Once it exists, the dashboard shows the usual login and sign-up pages. ## Environment Variables @@ -47,11 +49,10 @@ The web user interface communicates via REST to the API that powers the applicat Once you have created an account and some flags, you can then start using the API with one of the [Flagsmith Client SDKs](https://github.com/Flagsmith?q=client&type=&language=). You will need to override the API endpoint for each SDK to point to [http://localhost:8000/api/v1/](http://localhost:8000/api/v1/). -You can access the Django Admin console to get CRUD access to some of the core tables within the API. You will need to create a superuser account first with the following command: +You can access the Django Admin console to get CRUD access to some of the core tables within the API. The admin account you created on first run already has access. To create another superuser, run: ```bash -# Make sure you are in the root directory of this repository -docker-compose run --rm --entrypoint "python manage.py createsuperuser" api +docker compose exec flagsmith flagsmith createsuperuser ``` You can then access the admin dashboard at [http://localhost:8000/admin/](http://localhost:8000/admin/) diff --git a/frontend/README.md b/frontend/README.md index 7a4a4758b1db..b13e6e5f9774 100644 --- a/frontend/README.md +++ b/frontend/README.md @@ -9,12 +9,7 @@ curl -o docker-compose.yml https://raw.githubusercontent.com/Flagsmith/flagsmith docker-compose -f docker-compose.yml up ``` -The application will bootstrap an admin user, organisation, and project for you. You'll find a link to set your password in your Compose logs: - -```txt -Superuser "admin@example.com" created successfully. -Please go to the following page and choose a password: http://localhost:8000/password-reset/confirm/.../... -``` +Once the containers are up, open http://localhost:8000. On a fresh install, the dashboard walks you through creating your admin account and your first organisation. ### Local development From a86f269415b47124b7a71c3b0f904bd86dcfa384 Mon Sep 17 00:00:00 2001 From: wadii Date: Fri, 16 Oct 2026 11:25:46 +0200 Subject: [PATCH 2/4] docs: apply Prettier to the first-run admin pages --- README.md | 134 ++++++++++-------- .../using-the-django-admin.md | 42 ++++-- .../hosting-guides/docker.md | 49 +++++-- 3 files changed, 140 insertions(+), 85 deletions(-) diff --git a/README.md b/README.md index c10c87a8c75e..26d679e6c83c 100644 --- a/README.md +++ b/README.md @@ -12,25 +12,33 @@ ## What is Flagsmith? -Flagsmith is an open-source feature management platform that offers remote configuration and experimentation solutions. Choose from three deployment options: self-hosted (available as our free open-source build or a fully supported Enterprise edition), private cloud, and cloud. +Flagsmith is an open-source feature management platform that offers remote configuration and experimentation solutions. +Choose from three deployment options: self-hosted (available as our free open-source build or a fully supported +Enterprise edition), private cloud, and cloud. -As an open-source solution, Flagsmith provides flexibility and greater control over your choices. Thanks to our partnership with [OpenFeature](https://openfeature.dev/), you are never locked into one vendor. +As an open-source solution, Flagsmith provides flexibility and greater control over your choices. Thanks to our +partnership with [OpenFeature](https://openfeature.dev/), you are never locked into one vendor. -With Flagsmith, you can evolve how your team releases software. Roll out, segment, experiment, and optimise with granular control. Stay secure by self-hosting, or choosing our private cloud deployment option. +With Flagsmith, you can evolve how your team releases software. Roll out, segment, experiment, and optimise with +granular control. Stay secure by self-hosting, or choosing our private cloud deployment option. -* Feature flags: Release features behind the safety of a feature flag -* Make changes remotely: Easily toggle individual features on and off, and make changes without deploying new code -* A/B testing: Use segments to run A/B and multivariate tests on new features -* Segments: Release features to beta testers, collect feedback, and iterate -* Organisation management: Stay organised with orgs, projects, and roles for team members -* SDKs and frameworks: Choose from 15+ popular languages like TypeScript, .NET, Java, and more. Integrate with any framework, including React, Next.js, and more -* Integrations and MCP server: Use your favourite tools with Flagsmith +- Feature flags: Release features behind the safety of a feature flag +- Make changes remotely: Easily toggle individual features on and off, and make changes without deploying new code +- A/B testing: Use segments to run A/B and multivariate tests on new features +- Segments: Release features to beta testers, collect feedback, and iterate +- Organisation management: Stay organised with orgs, projects, and roles for team members +- SDKs and frameworks: Choose from 15+ popular languages like TypeScript, .NET, Java, and more. Integrate with any + framework, including React, Next.js, and more +- Integrations and MCP server: Use your favourite tools with Flagsmith -Flagsmith makes it easy to create and manage feature flags across web, mobile, and server-side applications. 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. +Flagsmith makes it easy to create and manage feature flags across web, mobile, and server-side applications. 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. ## See Flagsmith in action -If you want a step-by-step demonstration of how to get started with Flagsmith, why not [try our interactive demo](https://www.flagsmith.com/demo). +If you want a step-by-step demonstration of how to get started with Flagsmith, why not +[try our interactive demo](https://www.flagsmith.com/demo).

@@ -44,7 +52,9 @@ curl -o docker-compose.yml https://raw.githubusercontent.com/Flagsmith/flagsmith docker-compose -f docker-compose.yml up ``` -Once the containers are up, open [http://localhost:8000](http://localhost:8000). On a fresh install, the dashboard walks you through creating your admin account and your first organisation (learn more about Flagsmith terminology in our [data model docs](https://docs.flagsmith.com/flagsmith-concepts/data-model)). +Once the containers are up, open [http://localhost:8000](http://localhost:8000). On a fresh install, the dashboard walks +you through creating your admin account and your first organisation (learn more about Flagsmith terminology in our +[data model docs](https://docs.flagsmith.com/flagsmith-concepts/data-model)). ## Check a feature flag in your code @@ -54,24 +64,29 @@ Once Flagsmith is running, checking a flag takes one function call. Here's how i import flagsmith from 'flagsmith'; flagsmith.init({ - environmentID: '', - onChange: () => { - if (flagsmith.hasFeature('show_demo_button')) { - // show the new feature - } - }, + environmentID: '', + onChange: () => { + if (flagsmith.hasFeature('show_demo_button')) { + // show the new feature + } + }, }); ``` -As this example runs in the browser, you should use your client-side environment key. Server-side keys must stay secret and never appear in browser code. +As this example runs in the browser, you should use your client-side environment key. Server-side keys must stay secret +and never appear in browser code. -Follow the [quick start guide](https://docs.flagsmith.com/getting-started/quick-start) for the full walkthrough, or pick your language from our [SDK docs](https://docs.flagsmith.com/integrating-with-flagsmith/sdks) to see the same thing in Python, Java, Go, .NET, and more. +Follow the [quick start guide](https://docs.flagsmith.com/getting-started/quick-start) for the full walkthrough, or pick +your language from our [SDK docs](https://docs.flagsmith.com/integrating-with-flagsmith/sdks) to see the same thing in +Python, Java, Go, .NET, and more. ![Flagsmith Screenshot](static-files/screenshot.png) ## Contribute to Flagsmith Open Source -We love contributions from the community and are always looking to improve our [open-source feature management platform](https://www.flagsmith.com/)! Here are our [contribution guidelines](https://docs.flagsmith.com/project-and-community/contributing). +We love contributions from the community and are always looking to improve our +[open-source feature management platform](https://www.flagsmith.com/)! Here are our +[contribution guidelines](https://docs.flagsmith.com/project-and-community/contributing). ## Flagsmith hosted SaaS @@ -79,60 +94,67 @@ You can try our hosted version for free at [app.flagsmith.com/signup](https://ap ## Community Resources -* [Visit our docs](https://docs.flagsmith.com/) -* [Chat with other developers on Discord](https://discord.com/invite/hFhxNtXzgm) -* If you need help getting up and running, [get in touch](https://www.flagsmith.com/contact-us) +- [Visit our docs](https://docs.flagsmith.com/) +- [Chat with other developers on Discord](https://discord.com/invite/hFhxNtXzgm) +- If you need help getting up and running, [get in touch](https://www.flagsmith.com/contact-us) ## Available SDKs ### Client side ([docs](https://docs.flagsmith.com/integrating-with-flagsmith/sdks/client-side-sdks)) -* [JavaScript](https://docs.flagsmith.com/integrating-with-flagsmith/sdks/client-side-sdks/javascript) -* [React](https://docs.flagsmith.com/integrating-with-flagsmith/sdks/client-side-sdks/react) -* [Next.js and SSR](https://docs.flagsmith.com/integrating-with-flagsmith/sdks/client-side-sdks/nextjs-and-ssr) -* [Android](https://docs.flagsmith.com/integrating-with-flagsmith/sdks/client-side-sdks/android) -* [iOS](https://docs.flagsmith.com/integrating-with-flagsmith/sdks/client-side-sdks/ios) -* [Flutter](https://docs.flagsmith.com/integrating-with-flagsmith/sdks/client-side-sdks/flutter) +- [JavaScript](https://docs.flagsmith.com/integrating-with-flagsmith/sdks/client-side-sdks/javascript) +- [React](https://docs.flagsmith.com/integrating-with-flagsmith/sdks/client-side-sdks/react) +- [Next.js and SSR](https://docs.flagsmith.com/integrating-with-flagsmith/sdks/client-side-sdks/nextjs-and-ssr) +- [Android](https://docs.flagsmith.com/integrating-with-flagsmith/sdks/client-side-sdks/android) +- [iOS](https://docs.flagsmith.com/integrating-with-flagsmith/sdks/client-side-sdks/ios) +- [Flutter](https://docs.flagsmith.com/integrating-with-flagsmith/sdks/client-side-sdks/flutter) ### Server side ([docs](https://docs.flagsmith.com/integrating-with-flagsmith/sdks/server-side)) -* [Python](https://github.com/Flagsmith/flagsmith-python-client) -* [Java](https://github.com/Flagsmith/flagsmith-java-client) -* [.NET](https://github.com/Flagsmith/flagsmith-dotnet-client) -* [Node.js](https://github.com/Flagsmith/flagsmith-nodejs-client) -* [Ruby](https://github.com/Flagsmith/flagsmith-ruby-client) -* [PHP](https://github.com/Flagsmith/flagsmith-php-client) -* [Go](https://github.com/Flagsmith/flagsmith-go-client) -* [Rust](https://github.com/Flagsmith/flagsmith-rust-client) -* [Elixir](https://github.com/Flagsmith/flagsmith-elixir-client) +- [Python](https://github.com/Flagsmith/flagsmith-python-client) +- [Java](https://github.com/Flagsmith/flagsmith-java-client) +- [.NET](https://github.com/Flagsmith/flagsmith-dotnet-client) +- [Node.js](https://github.com/Flagsmith/flagsmith-nodejs-client) +- [Ruby](https://github.com/Flagsmith/flagsmith-ruby-client) +- [PHP](https://github.com/Flagsmith/flagsmith-php-client) +- [Go](https://github.com/Flagsmith/flagsmith-go-client) +- [Rust](https://github.com/Flagsmith/flagsmith-rust-client) +- [Elixir](https://github.com/Flagsmith/flagsmith-elixir-client) ### Using OpenFeature - -Prefer the vendor-neutral route? You can use Flagsmith through [OpenFeature](https://openfeature.dev/) with providers for the following languages: - -* [Go](https://github.com/open-feature/go-sdk-contrib/tree/main/providers/flagsmith) -* [Java](https://github.com/open-feature/java-sdk-contrib/tree/main/providers/flagsmith) -* [JavaScript (client-side)](https://github.com/open-feature/js-sdk-contrib/tree/main/libs/providers/flagsmith-client) -* [JavaScript (server-side)](https://github.com/open-feature/js-sdk-contrib/tree/main/libs/providers/flagsmith) -* [Kotlin](https://github.com/Flagsmith/flagsmith-openfeature-provider-kotlin) -* [.NET](https://github.com/open-feature/dotnet-sdk-contrib/tree/main/src/OpenFeature.Contrib.Providers.Flagsmith) -* [Python](https://github.com/Flagsmith/flagsmith-openfeature-provider-python) -* [Ruby](https://github.com/open-feature/ruby-sdk-contrib/tree/main/providers/openfeature-flagsmith-provider) -* [Rust](https://github.com/open-feature/rust-sdk-contrib/tree/main/crates/flagsmith) + +Prefer the vendor-neutral route? You can use Flagsmith through [OpenFeature](https://openfeature.dev/) with providers +for the following languages: + +- [Go](https://github.com/open-feature/go-sdk-contrib/tree/main/providers/flagsmith) +- [Java](https://github.com/open-feature/java-sdk-contrib/tree/main/providers/flagsmith) +- [JavaScript (client-side)](https://github.com/open-feature/js-sdk-contrib/tree/main/libs/providers/flagsmith-client) +- [JavaScript (server-side)](https://github.com/open-feature/js-sdk-contrib/tree/main/libs/providers/flagsmith) +- [Kotlin](https://github.com/Flagsmith/flagsmith-openfeature-provider-kotlin) +- [.NET](https://github.com/open-feature/dotnet-sdk-contrib/tree/main/src/OpenFeature.Contrib.Providers.Flagsmith) +- [Python](https://github.com/Flagsmith/flagsmith-openfeature-provider-python) +- [Ruby](https://github.com/open-feature/ruby-sdk-contrib/tree/main/providers/openfeature-flagsmith-provider) +- [Rust](https://github.com/open-feature/rust-sdk-contrib/tree/main/crates/flagsmith) Check out the [OpenFeature docs](https://docs.flagsmith.com/integrating-with-flagsmith/openfeature) for setup. ## Open-Source Philosophy -The majority of our platform is open source under the [BSD-3-Clause license](https://github.com/Flagsmith/flagsmith?tab=BSD-3-Clause-1-ov-file#readme). A small number of repositories are under the MIT license. +The majority of our platform is open source under the +[BSD-3-Clause license](https://github.com/Flagsmith/flagsmith?tab=BSD-3-Clause-1-ov-file#readme). A small number of +repositories are under the MIT license. -We built Flagsmith as the open-source feature flag tool we needed but couldn't find on GitHub. Our core functionality stays open, always. Read our [open letter to developers](https://www.flagsmith.com/about-us). +We built Flagsmith as the open-source feature flag tool we needed but couldn't find on GitHub. Our core functionality +stays open, always. Read our [open letter to developers](https://www.flagsmith.com/about-us). ## Open Source vs Paid -As our core functionality is open, you can use our open-source feature flag and remote config management platform no matter what. Enterprise-level governance and management features are available with a valid Flagsmith Enterprise license. +As our core functionality is open, you can use our open-source feature flag and remote config management platform no +matter what. Enterprise-level governance and management features are available with a valid Flagsmith Enterprise +license. -To learn more, [contact us](https://www.flagsmith.com/contact-us) or see our [version comparison](https://docs.flagsmith.com/version-comparison). +To learn more, [contact us](https://www.flagsmith.com/contact-us) or see our +[version comparison](https://docs.flagsmith.com/version-comparison). ## Contributors diff --git a/docs/docs/deployment-self-hosting/administration-and-maintenance/using-the-django-admin.md b/docs/docs/deployment-self-hosting/administration-and-maintenance/using-the-django-admin.md index cb797e71932c..b0a0db37adff 100644 --- a/docs/docs/deployment-self-hosting/administration-and-maintenance/using-the-django-admin.md +++ b/docs/docs/deployment-self-hosting/administration-and-maintenance/using-the-django-admin.md @@ -6,27 +6,37 @@ sidebar_position: 100 # Django Admin -The Flagsmith API is a Django application. As such, certain administrative tasks can be performed using [Django's built-in admin interface](https://docs.djangoproject.com/en/4.2/ref/contrib/admin/), which we refer to as Django Admin. +The Flagsmith API is a Django application. As such, certain administrative tasks can be performed using +[Django's built-in admin interface](https://docs.djangoproject.com/en/4.2/ref/contrib/admin/), which we refer to as +Django Admin. :::danger -Improper use of Django Admin can cause data loss and make your Flagsmith instance unusable. Make sure to control who has access, and only perform tasks as directed by Flagsmith staff. +Improper use of Django Admin can cause data loss and make your Flagsmith instance unusable. Make sure to control who has +access, and only perform tasks as directed by Flagsmith staff. -::: +::: ## Accessing Django Admin Django Admin can be accessed from the `/admin/` route on the Flagsmith API. Note that the trailing slash is important. -Accessing Django Admin requires a user with [`is_staff`](https://docs.djangoproject.com/en/4.2/ref/contrib/auth/#django.contrib.auth.models.User.is_staff) set. This does not grant any additional permissions beyond accessing Django Admin itself. +Accessing Django Admin requires a user with +[`is_staff`](https://docs.djangoproject.com/en/4.2/ref/contrib/auth/#django.contrib.auth.models.User.is_staff) set. This +does not grant any additional permissions beyond accessing Django Admin itself. -A user with [`is_superuser`](https://docs.djangoproject.com/en/4.2/ref/contrib/auth/#django.contrib.auth.models.User.is_superuser) is granted all permissions. Note that superusers still require `is_staff` to access Django Admin. +A user with +[`is_superuser`](https://docs.djangoproject.com/en/4.2/ref/contrib/auth/#django.contrib.auth.models.User.is_superuser) +is granted all permissions. Note that superusers still require `is_staff` to access Django Admin. You can obtain a user with these permissions using any of these methods: -* Use the [`createsuperuser` management command](/deployment-self-hosting/core-configuration/initial-setup#from-the-command-line) from a Flagsmith API shell. -* If no users exist yet, [create the first account from the dashboard](/deployment-self-hosting/core-configuration/initial-setup#from-the-dashboard-recommended). -* Manually set the `is_staff` and `is_superuser` database fields for your user in the `users_ffadminuser` table. +- Use the + [`createsuperuser` management command](/deployment-self-hosting/core-configuration/initial-setup#from-the-command-line) + from a Flagsmith API shell. +- If no users exist yet, + [create the first account from the dashboard](/deployment-self-hosting/core-configuration/initial-setup#from-the-dashboard-recommended). +- Manually set the `is_staff` and `is_superuser` database fields for your user in the `users_ffadminuser` table. ## Authentication @@ -34,22 +44,26 @@ You can log in to Django Admin using the same email and password you use to log ### Email and Password -To log in to Django Admin with a password, make sure the Flagsmith API has the `ENABLE_ADMIN_ACCESS_USER_PASS` environment variable set to `true`. +To log in to Django Admin with a password, make sure the Flagsmith API has the `ENABLE_ADMIN_ACCESS_USER_PASS` +environment variable set to `true`. If your Flagsmith account does not have a password, you can create one using any of these methods: -* From the Flagsmith login page, click "Forgot password". Make sure your Flagsmith API is [configured to send emails](/deployment-self-hosting/core-configuration/email-setup). -* From a Flagsmith API shell, run `python manage.py changepassword your_email@example.com` and type a password. +- From the Flagsmith login page, click "Forgot password". Make sure your Flagsmith API is + [configured to send emails](/deployment-self-hosting/core-configuration/email-setup). +- From a Flagsmith API shell, run `python manage.py changepassword your_email@example.com` and type a password. ### Google Google accounts use OAuth 2.0, which requires TLS. -To set up Google authentication for Django Admin, create an OAuth client ID and secret from the [Google Developer Console](https://console.developers.google.com/project). The redirect URI should point to `/admin/admin_sso/assignment/end/` on your API domain. +To set up Google authentication for Django Admin, create an OAuth client ID and secret from the +[Google Developer Console](https://console.developers.google.com/project). The redirect URI should point to +`/admin/admin_sso/assignment/end/` on your API domain. Set your Google OAuth client ID and secret in the following Flagsmith API environment variables: -* `OAUTH_CLIENT_ID` -* `OAUTH_CLIENT_SECRET` +- `OAUTH_CLIENT_ID` +- `OAUTH_CLIENT_SECRET` To log in with Google, click "Log in using SSO" from the Django Admin login page. diff --git a/docs/docs/deployment-self-hosting/hosting-guides/docker.md b/docs/docs/deployment-self-hosting/hosting-guides/docker.md index 0621571c8d88..440a487d82fb 100644 --- a/docs/docs/deployment-self-hosting/hosting-guides/docker.md +++ b/docs/docs/deployment-self-hosting/hosting-guides/docker.md @@ -5,7 +5,8 @@ description: Getting Started with Flagsmith on Docker sidebar_position: 1 --- -This guide explains how to run a full Flagsmith environment on your local machine using Docker. This is useful for development, testing, or evaluating Flagsmith's features. +This guide explains how to run a full Flagsmith environment on your local machine using Docker. This is useful for +development, testing, or evaluating Flagsmith's features. You can use Docker to set up an entire [Flagsmith Feature Flag](https://www.flagsmith.com) environment locally: @@ -14,19 +15,29 @@ curl -o docker-compose.yml https://raw.githubusercontent.com/Flagsmith/flagsmith docker-compose -f docker-compose.yml up ``` -Wait for the images to download and run, then visit [http://localhost:8000](http://localhost:8000). On a fresh install, the dashboard shows a **Welcome to Flagsmith** screen: select **Get Started** to create your admin account and your first organisation. Nothing is printed to the Compose logs for this step. +Wait for the images to download and run, then visit [http://localhost:8000](http://localhost:8000). On a fresh install, +the dashboard shows a **Welcome to Flagsmith** screen: select **Get Started** to create your admin account and your +first organisation. Nothing is printed to the Compose logs for this step. This first account is a superuser. Once it exists, the dashboard shows the usual login and sign-up pages. ## Environment Variables -As well as the Environment Variables specified in the [API](/deployment-self-hosting/core-configuration/environment-variables#api-environment-variables) and [Frontend](/deployment-self-hosting/core-configuration/environment-variables#frontend-environment-variables), you can also specify the following: - -- `GUNICORN_CMD_ARGS`: Gunicorn command line arguments. Overrides Flagsmith's defaults. See [Gunicorn documentation](https://docs.gunicorn.org/en/stable/settings.html) for reference. -- `GUNICORN_WORKERS`: The number of [Gunicorn Workers](https://docs.gunicorn.org/en/stable/settings.html#workers) that are created -- `GUNICORN_THREADS`: The number of [Gunicorn Threads per Worker](https://docs.gunicorn.org/en/stable/settings.html#threads) -- `GUNICORN_TIMEOUT`: The number of seconds before the [Gunicorn times out](https://docs.gunicorn.org/en/stable/settings.html#timeout) -- `ACCESS_LOG_FORMAT`: Message format for Gunicorn's access log. See [variable details](https://docs.gunicorn.org/en/stable/settings.html#access-log-format) to define your own format. +As well as the Environment Variables specified in the +[API](/deployment-self-hosting/core-configuration/environment-variables#api-environment-variables) and +[Frontend](/deployment-self-hosting/core-configuration/environment-variables#frontend-environment-variables), you can +also specify the following: + +- `GUNICORN_CMD_ARGS`: Gunicorn command line arguments. Overrides Flagsmith's defaults. See + [Gunicorn documentation](https://docs.gunicorn.org/en/stable/settings.html) for reference. +- `GUNICORN_WORKERS`: The number of [Gunicorn Workers](https://docs.gunicorn.org/en/stable/settings.html#workers) that + are created +- `GUNICORN_THREADS`: The number of + [Gunicorn Threads per Worker](https://docs.gunicorn.org/en/stable/settings.html#threads) +- `GUNICORN_TIMEOUT`: The number of seconds before the + [Gunicorn times out](https://docs.gunicorn.org/en/stable/settings.html#timeout) +- `ACCESS_LOG_FORMAT`: Message format for Gunicorn's access log. See + [variable details](https://docs.gunicorn.org/en/stable/settings.html#access-log-format) to define your own format. - `ACCESS_LOG_LOCATION`: The location to write access logs to. If set to `-`, the logs will be sent to `stdout` ## Platform Architectures @@ -43,13 +54,18 @@ The docker-compose file runs the following containers: ### Frontend Dashboard and REST API Combined - Port 8000 -The web user interface allows you to create accounts and manage your flags. The frontend is written in Node.js and React. +The web user interface allows you to create accounts and manage your flags. The frontend is written in Node.js and +React. -The web user interface communicates via REST to the API that powers the application. The SDK clients also connect to this API. The API is written in Django and the Django REST Framework. +The web user interface communicates via REST to the API that powers the application. The SDK clients also connect to +this API. The API is written in Django and the Django REST Framework. -Once you have created an account and some flags, you can then start using the API with one of the [Flagsmith Client SDKs](https://github.com/Flagsmith?q=client&type=&language=). You will need to override the API endpoint for each SDK to point to [http://localhost:8000/api/v1/](http://localhost:8000/api/v1/). +Once you have created an account and some flags, you can then start using the API with one of the +[Flagsmith Client SDKs](https://github.com/Flagsmith?q=client&type=&language=). You will need to override the API +endpoint for each SDK to point to [http://localhost:8000/api/v1/](http://localhost:8000/api/v1/). -You can access the Django Admin console to get CRUD access to some of the core tables within the API. The admin account you created on first run already has access. To create another superuser, run: +You can access the Django Admin console to get CRUD access to some of the core tables within the API. The admin account +you created on first run already has access. To create another superuser, run: ```bash docker compose exec flagsmith flagsmith createsuperuser @@ -59,8 +75,11 @@ You can then access the admin dashboard at [http://localhost:8000/admin/](http:/ ### PostgreSQL Database -The REST API stores all its data within a PostgreSQL database. Schema changes will be carried out automatically when upgrading using Django Migrations. +The REST API stores all its data within a PostgreSQL database. Schema changes will be carried out automatically when +upgrading using Django Migrations. ## Access Flagsmith Remotely -You will need to either open ports into your Docker host or set up a reverse proxy to access the two Flagsmith services (dashboard and API). You will also need to configure the dashboard environment variable `API_URL`, which tells the dashboard where the REST API is located. +You will need to either open ports into your Docker host or set up a reverse proxy to access the two Flagsmith services +(dashboard and API). You will also need to configure the dashboard environment variable `API_URL`, which tells the +dashboard where the REST API is located. From cf4863c6d8f813dc162dd48081aa8750b61c2b88 Mon Sep 17 00:00:00 2001 From: wadii Date: Fri, 16 Oct 2026 14:45:29 +0200 Subject: [PATCH 3/4] docs: revert unrelated Prettier reformatting --- README.md | 134 ++++++++---------- .../using-the-django-admin.md | 42 ++---- .../core-configuration/initial-setup.md | 4 +- .../hosting-guides/docker.md | 49 ++----- 4 files changed, 87 insertions(+), 142 deletions(-) diff --git a/README.md b/README.md index 26d679e6c83c..c10c87a8c75e 100644 --- a/README.md +++ b/README.md @@ -12,33 +12,25 @@ ## What is Flagsmith? -Flagsmith is an open-source feature management platform that offers remote configuration and experimentation solutions. -Choose from three deployment options: self-hosted (available as our free open-source build or a fully supported -Enterprise edition), private cloud, and cloud. +Flagsmith is an open-source feature management platform that offers remote configuration and experimentation solutions. Choose from three deployment options: self-hosted (available as our free open-source build or a fully supported Enterprise edition), private cloud, and cloud. -As an open-source solution, Flagsmith provides flexibility and greater control over your choices. Thanks to our -partnership with [OpenFeature](https://openfeature.dev/), you are never locked into one vendor. +As an open-source solution, Flagsmith provides flexibility and greater control over your choices. Thanks to our partnership with [OpenFeature](https://openfeature.dev/), you are never locked into one vendor. -With Flagsmith, you can evolve how your team releases software. Roll out, segment, experiment, and optimise with -granular control. Stay secure by self-hosting, or choosing our private cloud deployment option. +With Flagsmith, you can evolve how your team releases software. Roll out, segment, experiment, and optimise with granular control. Stay secure by self-hosting, or choosing our private cloud deployment option. -- Feature flags: Release features behind the safety of a feature flag -- Make changes remotely: Easily toggle individual features on and off, and make changes without deploying new code -- A/B testing: Use segments to run A/B and multivariate tests on new features -- Segments: Release features to beta testers, collect feedback, and iterate -- Organisation management: Stay organised with orgs, projects, and roles for team members -- SDKs and frameworks: Choose from 15+ popular languages like TypeScript, .NET, Java, and more. Integrate with any - framework, including React, Next.js, and more -- Integrations and MCP server: Use your favourite tools with Flagsmith +* Feature flags: Release features behind the safety of a feature flag +* Make changes remotely: Easily toggle individual features on and off, and make changes without deploying new code +* A/B testing: Use segments to run A/B and multivariate tests on new features +* Segments: Release features to beta testers, collect feedback, and iterate +* Organisation management: Stay organised with orgs, projects, and roles for team members +* SDKs and frameworks: Choose from 15+ popular languages like TypeScript, .NET, Java, and more. Integrate with any framework, including React, Next.js, and more +* Integrations and MCP server: Use your favourite tools with Flagsmith -Flagsmith makes it easy to create and manage feature flags across web, mobile, and server-side applications. 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. +Flagsmith makes it easy to create and manage feature flags across web, mobile, and server-side applications. 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. ## See Flagsmith in action -If you want a step-by-step demonstration of how to get started with Flagsmith, why not -[try our interactive demo](https://www.flagsmith.com/demo). +If you want a step-by-step demonstration of how to get started with Flagsmith, why not [try our interactive demo](https://www.flagsmith.com/demo).

@@ -52,9 +44,7 @@ curl -o docker-compose.yml https://raw.githubusercontent.com/Flagsmith/flagsmith docker-compose -f docker-compose.yml up ``` -Once the containers are up, open [http://localhost:8000](http://localhost:8000). On a fresh install, the dashboard walks -you through creating your admin account and your first organisation (learn more about Flagsmith terminology in our -[data model docs](https://docs.flagsmith.com/flagsmith-concepts/data-model)). +Once the containers are up, open [http://localhost:8000](http://localhost:8000). On a fresh install, the dashboard walks you through creating your admin account and your first organisation (learn more about Flagsmith terminology in our [data model docs](https://docs.flagsmith.com/flagsmith-concepts/data-model)). ## Check a feature flag in your code @@ -64,29 +54,24 @@ Once Flagsmith is running, checking a flag takes one function call. Here's how i import flagsmith from 'flagsmith'; flagsmith.init({ - environmentID: '', - onChange: () => { - if (flagsmith.hasFeature('show_demo_button')) { - // show the new feature - } - }, + environmentID: '', + onChange: () => { + if (flagsmith.hasFeature('show_demo_button')) { + // show the new feature + } + }, }); ``` -As this example runs in the browser, you should use your client-side environment key. Server-side keys must stay secret -and never appear in browser code. +As this example runs in the browser, you should use your client-side environment key. Server-side keys must stay secret and never appear in browser code. -Follow the [quick start guide](https://docs.flagsmith.com/getting-started/quick-start) for the full walkthrough, or pick -your language from our [SDK docs](https://docs.flagsmith.com/integrating-with-flagsmith/sdks) to see the same thing in -Python, Java, Go, .NET, and more. +Follow the [quick start guide](https://docs.flagsmith.com/getting-started/quick-start) for the full walkthrough, or pick your language from our [SDK docs](https://docs.flagsmith.com/integrating-with-flagsmith/sdks) to see the same thing in Python, Java, Go, .NET, and more. ![Flagsmith Screenshot](static-files/screenshot.png) ## Contribute to Flagsmith Open Source -We love contributions from the community and are always looking to improve our -[open-source feature management platform](https://www.flagsmith.com/)! Here are our -[contribution guidelines](https://docs.flagsmith.com/project-and-community/contributing). +We love contributions from the community and are always looking to improve our [open-source feature management platform](https://www.flagsmith.com/)! Here are our [contribution guidelines](https://docs.flagsmith.com/project-and-community/contributing). ## Flagsmith hosted SaaS @@ -94,67 +79,60 @@ You can try our hosted version for free at [app.flagsmith.com/signup](https://ap ## Community Resources -- [Visit our docs](https://docs.flagsmith.com/) -- [Chat with other developers on Discord](https://discord.com/invite/hFhxNtXzgm) -- If you need help getting up and running, [get in touch](https://www.flagsmith.com/contact-us) +* [Visit our docs](https://docs.flagsmith.com/) +* [Chat with other developers on Discord](https://discord.com/invite/hFhxNtXzgm) +* If you need help getting up and running, [get in touch](https://www.flagsmith.com/contact-us) ## Available SDKs ### Client side ([docs](https://docs.flagsmith.com/integrating-with-flagsmith/sdks/client-side-sdks)) -- [JavaScript](https://docs.flagsmith.com/integrating-with-flagsmith/sdks/client-side-sdks/javascript) -- [React](https://docs.flagsmith.com/integrating-with-flagsmith/sdks/client-side-sdks/react) -- [Next.js and SSR](https://docs.flagsmith.com/integrating-with-flagsmith/sdks/client-side-sdks/nextjs-and-ssr) -- [Android](https://docs.flagsmith.com/integrating-with-flagsmith/sdks/client-side-sdks/android) -- [iOS](https://docs.flagsmith.com/integrating-with-flagsmith/sdks/client-side-sdks/ios) -- [Flutter](https://docs.flagsmith.com/integrating-with-flagsmith/sdks/client-side-sdks/flutter) +* [JavaScript](https://docs.flagsmith.com/integrating-with-flagsmith/sdks/client-side-sdks/javascript) +* [React](https://docs.flagsmith.com/integrating-with-flagsmith/sdks/client-side-sdks/react) +* [Next.js and SSR](https://docs.flagsmith.com/integrating-with-flagsmith/sdks/client-side-sdks/nextjs-and-ssr) +* [Android](https://docs.flagsmith.com/integrating-with-flagsmith/sdks/client-side-sdks/android) +* [iOS](https://docs.flagsmith.com/integrating-with-flagsmith/sdks/client-side-sdks/ios) +* [Flutter](https://docs.flagsmith.com/integrating-with-flagsmith/sdks/client-side-sdks/flutter) ### Server side ([docs](https://docs.flagsmith.com/integrating-with-flagsmith/sdks/server-side)) -- [Python](https://github.com/Flagsmith/flagsmith-python-client) -- [Java](https://github.com/Flagsmith/flagsmith-java-client) -- [.NET](https://github.com/Flagsmith/flagsmith-dotnet-client) -- [Node.js](https://github.com/Flagsmith/flagsmith-nodejs-client) -- [Ruby](https://github.com/Flagsmith/flagsmith-ruby-client) -- [PHP](https://github.com/Flagsmith/flagsmith-php-client) -- [Go](https://github.com/Flagsmith/flagsmith-go-client) -- [Rust](https://github.com/Flagsmith/flagsmith-rust-client) -- [Elixir](https://github.com/Flagsmith/flagsmith-elixir-client) +* [Python](https://github.com/Flagsmith/flagsmith-python-client) +* [Java](https://github.com/Flagsmith/flagsmith-java-client) +* [.NET](https://github.com/Flagsmith/flagsmith-dotnet-client) +* [Node.js](https://github.com/Flagsmith/flagsmith-nodejs-client) +* [Ruby](https://github.com/Flagsmith/flagsmith-ruby-client) +* [PHP](https://github.com/Flagsmith/flagsmith-php-client) +* [Go](https://github.com/Flagsmith/flagsmith-go-client) +* [Rust](https://github.com/Flagsmith/flagsmith-rust-client) +* [Elixir](https://github.com/Flagsmith/flagsmith-elixir-client) ### Using OpenFeature - -Prefer the vendor-neutral route? You can use Flagsmith through [OpenFeature](https://openfeature.dev/) with providers -for the following languages: - -- [Go](https://github.com/open-feature/go-sdk-contrib/tree/main/providers/flagsmith) -- [Java](https://github.com/open-feature/java-sdk-contrib/tree/main/providers/flagsmith) -- [JavaScript (client-side)](https://github.com/open-feature/js-sdk-contrib/tree/main/libs/providers/flagsmith-client) -- [JavaScript (server-side)](https://github.com/open-feature/js-sdk-contrib/tree/main/libs/providers/flagsmith) -- [Kotlin](https://github.com/Flagsmith/flagsmith-openfeature-provider-kotlin) -- [.NET](https://github.com/open-feature/dotnet-sdk-contrib/tree/main/src/OpenFeature.Contrib.Providers.Flagsmith) -- [Python](https://github.com/Flagsmith/flagsmith-openfeature-provider-python) -- [Ruby](https://github.com/open-feature/ruby-sdk-contrib/tree/main/providers/openfeature-flagsmith-provider) -- [Rust](https://github.com/open-feature/rust-sdk-contrib/tree/main/crates/flagsmith) + +Prefer the vendor-neutral route? You can use Flagsmith through [OpenFeature](https://openfeature.dev/) with providers for the following languages: + +* [Go](https://github.com/open-feature/go-sdk-contrib/tree/main/providers/flagsmith) +* [Java](https://github.com/open-feature/java-sdk-contrib/tree/main/providers/flagsmith) +* [JavaScript (client-side)](https://github.com/open-feature/js-sdk-contrib/tree/main/libs/providers/flagsmith-client) +* [JavaScript (server-side)](https://github.com/open-feature/js-sdk-contrib/tree/main/libs/providers/flagsmith) +* [Kotlin](https://github.com/Flagsmith/flagsmith-openfeature-provider-kotlin) +* [.NET](https://github.com/open-feature/dotnet-sdk-contrib/tree/main/src/OpenFeature.Contrib.Providers.Flagsmith) +* [Python](https://github.com/Flagsmith/flagsmith-openfeature-provider-python) +* [Ruby](https://github.com/open-feature/ruby-sdk-contrib/tree/main/providers/openfeature-flagsmith-provider) +* [Rust](https://github.com/open-feature/rust-sdk-contrib/tree/main/crates/flagsmith) Check out the [OpenFeature docs](https://docs.flagsmith.com/integrating-with-flagsmith/openfeature) for setup. ## Open-Source Philosophy -The majority of our platform is open source under the -[BSD-3-Clause license](https://github.com/Flagsmith/flagsmith?tab=BSD-3-Clause-1-ov-file#readme). A small number of -repositories are under the MIT license. +The majority of our platform is open source under the [BSD-3-Clause license](https://github.com/Flagsmith/flagsmith?tab=BSD-3-Clause-1-ov-file#readme). A small number of repositories are under the MIT license. -We built Flagsmith as the open-source feature flag tool we needed but couldn't find on GitHub. Our core functionality -stays open, always. Read our [open letter to developers](https://www.flagsmith.com/about-us). +We built Flagsmith as the open-source feature flag tool we needed but couldn't find on GitHub. Our core functionality stays open, always. Read our [open letter to developers](https://www.flagsmith.com/about-us). ## Open Source vs Paid -As our core functionality is open, you can use our open-source feature flag and remote config management platform no -matter what. Enterprise-level governance and management features are available with a valid Flagsmith Enterprise -license. +As our core functionality is open, you can use our open-source feature flag and remote config management platform no matter what. Enterprise-level governance and management features are available with a valid Flagsmith Enterprise license. -To learn more, [contact us](https://www.flagsmith.com/contact-us) or see our -[version comparison](https://docs.flagsmith.com/version-comparison). +To learn more, [contact us](https://www.flagsmith.com/contact-us) or see our [version comparison](https://docs.flagsmith.com/version-comparison). ## Contributors diff --git a/docs/docs/deployment-self-hosting/administration-and-maintenance/using-the-django-admin.md b/docs/docs/deployment-self-hosting/administration-and-maintenance/using-the-django-admin.md index b0a0db37adff..cb797e71932c 100644 --- a/docs/docs/deployment-self-hosting/administration-and-maintenance/using-the-django-admin.md +++ b/docs/docs/deployment-self-hosting/administration-and-maintenance/using-the-django-admin.md @@ -6,37 +6,27 @@ sidebar_position: 100 # Django Admin -The Flagsmith API is a Django application. As such, certain administrative tasks can be performed using -[Django's built-in admin interface](https://docs.djangoproject.com/en/4.2/ref/contrib/admin/), which we refer to as -Django Admin. +The Flagsmith API is a Django application. As such, certain administrative tasks can be performed using [Django's built-in admin interface](https://docs.djangoproject.com/en/4.2/ref/contrib/admin/), which we refer to as Django Admin. :::danger -Improper use of Django Admin can cause data loss and make your Flagsmith instance unusable. Make sure to control who has -access, and only perform tasks as directed by Flagsmith staff. +Improper use of Django Admin can cause data loss and make your Flagsmith instance unusable. Make sure to control who has access, and only perform tasks as directed by Flagsmith staff. -::: +::: ## Accessing Django Admin Django Admin can be accessed from the `/admin/` route on the Flagsmith API. Note that the trailing slash is important. -Accessing Django Admin requires a user with -[`is_staff`](https://docs.djangoproject.com/en/4.2/ref/contrib/auth/#django.contrib.auth.models.User.is_staff) set. This -does not grant any additional permissions beyond accessing Django Admin itself. +Accessing Django Admin requires a user with [`is_staff`](https://docs.djangoproject.com/en/4.2/ref/contrib/auth/#django.contrib.auth.models.User.is_staff) set. This does not grant any additional permissions beyond accessing Django Admin itself. -A user with -[`is_superuser`](https://docs.djangoproject.com/en/4.2/ref/contrib/auth/#django.contrib.auth.models.User.is_superuser) -is granted all permissions. Note that superusers still require `is_staff` to access Django Admin. +A user with [`is_superuser`](https://docs.djangoproject.com/en/4.2/ref/contrib/auth/#django.contrib.auth.models.User.is_superuser) is granted all permissions. Note that superusers still require `is_staff` to access Django Admin. You can obtain a user with these permissions using any of these methods: -- Use the - [`createsuperuser` management command](/deployment-self-hosting/core-configuration/initial-setup#from-the-command-line) - from a Flagsmith API shell. -- If no users exist yet, - [create the first account from the dashboard](/deployment-self-hosting/core-configuration/initial-setup#from-the-dashboard-recommended). -- Manually set the `is_staff` and `is_superuser` database fields for your user in the `users_ffadminuser` table. +* Use the [`createsuperuser` management command](/deployment-self-hosting/core-configuration/initial-setup#from-the-command-line) from a Flagsmith API shell. +* If no users exist yet, [create the first account from the dashboard](/deployment-self-hosting/core-configuration/initial-setup#from-the-dashboard-recommended). +* Manually set the `is_staff` and `is_superuser` database fields for your user in the `users_ffadminuser` table. ## Authentication @@ -44,26 +34,22 @@ You can log in to Django Admin using the same email and password you use to log ### Email and Password -To log in to Django Admin with a password, make sure the Flagsmith API has the `ENABLE_ADMIN_ACCESS_USER_PASS` -environment variable set to `true`. +To log in to Django Admin with a password, make sure the Flagsmith API has the `ENABLE_ADMIN_ACCESS_USER_PASS` environment variable set to `true`. If your Flagsmith account does not have a password, you can create one using any of these methods: -- From the Flagsmith login page, click "Forgot password". Make sure your Flagsmith API is - [configured to send emails](/deployment-self-hosting/core-configuration/email-setup). -- From a Flagsmith API shell, run `python manage.py changepassword your_email@example.com` and type a password. +* From the Flagsmith login page, click "Forgot password". Make sure your Flagsmith API is [configured to send emails](/deployment-self-hosting/core-configuration/email-setup). +* From a Flagsmith API shell, run `python manage.py changepassword your_email@example.com` and type a password. ### Google Google accounts use OAuth 2.0, which requires TLS. -To set up Google authentication for Django Admin, create an OAuth client ID and secret from the -[Google Developer Console](https://console.developers.google.com/project). The redirect URI should point to -`/admin/admin_sso/assignment/end/` on your API domain. +To set up Google authentication for Django Admin, create an OAuth client ID and secret from the [Google Developer Console](https://console.developers.google.com/project). The redirect URI should point to `/admin/admin_sso/assignment/end/` on your API domain. Set your Google OAuth client ID and secret in the following Flagsmith API environment variables: -- `OAUTH_CLIENT_ID` -- `OAUTH_CLIENT_SECRET` +* `OAUTH_CLIENT_ID` +* `OAUTH_CLIENT_SECRET` To log in with Google, click "Log in using SSO" from the Django Admin login page. diff --git a/docs/docs/deployment-self-hosting/core-configuration/initial-setup.md b/docs/docs/deployment-self-hosting/core-configuration/initial-setup.md index bfa68feaf236..b8047cb47b07 100644 --- a/docs/docs/deployment-self-hosting/core-configuration/initial-setup.md +++ b/docs/docs/deployment-self-hosting/core-configuration/initial-setup.md @@ -1,6 +1,6 @@ --- -title: 'Initial Setup' -description: 'How to initialise the instance and create the first superuser.' +title: "Initial Setup" +description: "How to initialise the instance and create the first superuser." sidebar_position: 10 --- diff --git a/docs/docs/deployment-self-hosting/hosting-guides/docker.md b/docs/docs/deployment-self-hosting/hosting-guides/docker.md index 440a487d82fb..0621571c8d88 100644 --- a/docs/docs/deployment-self-hosting/hosting-guides/docker.md +++ b/docs/docs/deployment-self-hosting/hosting-guides/docker.md @@ -5,8 +5,7 @@ description: Getting Started with Flagsmith on Docker sidebar_position: 1 --- -This guide explains how to run a full Flagsmith environment on your local machine using Docker. This is useful for -development, testing, or evaluating Flagsmith's features. +This guide explains how to run a full Flagsmith environment on your local machine using Docker. This is useful for development, testing, or evaluating Flagsmith's features. You can use Docker to set up an entire [Flagsmith Feature Flag](https://www.flagsmith.com) environment locally: @@ -15,29 +14,19 @@ curl -o docker-compose.yml https://raw.githubusercontent.com/Flagsmith/flagsmith docker-compose -f docker-compose.yml up ``` -Wait for the images to download and run, then visit [http://localhost:8000](http://localhost:8000). On a fresh install, -the dashboard shows a **Welcome to Flagsmith** screen: select **Get Started** to create your admin account and your -first organisation. Nothing is printed to the Compose logs for this step. +Wait for the images to download and run, then visit [http://localhost:8000](http://localhost:8000). On a fresh install, the dashboard shows a **Welcome to Flagsmith** screen: select **Get Started** to create your admin account and your first organisation. Nothing is printed to the Compose logs for this step. This first account is a superuser. Once it exists, the dashboard shows the usual login and sign-up pages. ## Environment Variables -As well as the Environment Variables specified in the -[API](/deployment-self-hosting/core-configuration/environment-variables#api-environment-variables) and -[Frontend](/deployment-self-hosting/core-configuration/environment-variables#frontend-environment-variables), you can -also specify the following: - -- `GUNICORN_CMD_ARGS`: Gunicorn command line arguments. Overrides Flagsmith's defaults. See - [Gunicorn documentation](https://docs.gunicorn.org/en/stable/settings.html) for reference. -- `GUNICORN_WORKERS`: The number of [Gunicorn Workers](https://docs.gunicorn.org/en/stable/settings.html#workers) that - are created -- `GUNICORN_THREADS`: The number of - [Gunicorn Threads per Worker](https://docs.gunicorn.org/en/stable/settings.html#threads) -- `GUNICORN_TIMEOUT`: The number of seconds before the - [Gunicorn times out](https://docs.gunicorn.org/en/stable/settings.html#timeout) -- `ACCESS_LOG_FORMAT`: Message format for Gunicorn's access log. See - [variable details](https://docs.gunicorn.org/en/stable/settings.html#access-log-format) to define your own format. +As well as the Environment Variables specified in the [API](/deployment-self-hosting/core-configuration/environment-variables#api-environment-variables) and [Frontend](/deployment-self-hosting/core-configuration/environment-variables#frontend-environment-variables), you can also specify the following: + +- `GUNICORN_CMD_ARGS`: Gunicorn command line arguments. Overrides Flagsmith's defaults. See [Gunicorn documentation](https://docs.gunicorn.org/en/stable/settings.html) for reference. +- `GUNICORN_WORKERS`: The number of [Gunicorn Workers](https://docs.gunicorn.org/en/stable/settings.html#workers) that are created +- `GUNICORN_THREADS`: The number of [Gunicorn Threads per Worker](https://docs.gunicorn.org/en/stable/settings.html#threads) +- `GUNICORN_TIMEOUT`: The number of seconds before the [Gunicorn times out](https://docs.gunicorn.org/en/stable/settings.html#timeout) +- `ACCESS_LOG_FORMAT`: Message format for Gunicorn's access log. See [variable details](https://docs.gunicorn.org/en/stable/settings.html#access-log-format) to define your own format. - `ACCESS_LOG_LOCATION`: The location to write access logs to. If set to `-`, the logs will be sent to `stdout` ## Platform Architectures @@ -54,18 +43,13 @@ The docker-compose file runs the following containers: ### Frontend Dashboard and REST API Combined - Port 8000 -The web user interface allows you to create accounts and manage your flags. The frontend is written in Node.js and -React. +The web user interface allows you to create accounts and manage your flags. The frontend is written in Node.js and React. -The web user interface communicates via REST to the API that powers the application. The SDK clients also connect to -this API. The API is written in Django and the Django REST Framework. +The web user interface communicates via REST to the API that powers the application. The SDK clients also connect to this API. The API is written in Django and the Django REST Framework. -Once you have created an account and some flags, you can then start using the API with one of the -[Flagsmith Client SDKs](https://github.com/Flagsmith?q=client&type=&language=). You will need to override the API -endpoint for each SDK to point to [http://localhost:8000/api/v1/](http://localhost:8000/api/v1/). +Once you have created an account and some flags, you can then start using the API with one of the [Flagsmith Client SDKs](https://github.com/Flagsmith?q=client&type=&language=). You will need to override the API endpoint for each SDK to point to [http://localhost:8000/api/v1/](http://localhost:8000/api/v1/). -You can access the Django Admin console to get CRUD access to some of the core tables within the API. The admin account -you created on first run already has access. To create another superuser, run: +You can access the Django Admin console to get CRUD access to some of the core tables within the API. The admin account you created on first run already has access. To create another superuser, run: ```bash docker compose exec flagsmith flagsmith createsuperuser @@ -75,11 +59,8 @@ You can then access the admin dashboard at [http://localhost:8000/admin/](http:/ ### PostgreSQL Database -The REST API stores all its data within a PostgreSQL database. Schema changes will be carried out automatically when -upgrading using Django Migrations. +The REST API stores all its data within a PostgreSQL database. Schema changes will be carried out automatically when upgrading using Django Migrations. ## Access Flagsmith Remotely -You will need to either open ports into your Docker host or set up a reverse proxy to access the two Flagsmith services -(dashboard and API). You will also need to configure the dashboard environment variable `API_URL`, which tells the -dashboard where the REST API is located. +You will need to either open ports into your Docker host or set up a reverse proxy to access the two Flagsmith services (dashboard and API). You will also need to configure the dashboard environment variable `API_URL`, which tells the dashboard where the REST API is located. From 90636402cf19d19858438a77ff9b28fd46681a48 Mon Sep 17 00:00:00 2001 From: wadii Date: Fri, 16 Oct 2026 17:09:25 +0200 Subject: [PATCH 4/4] docs: note Django Admin password login needs ENABLE_ADMIN_ACCESS_USER_PASS --- .../core-configuration/initial-setup.md | 5 +++-- docs/docs/deployment-self-hosting/hosting-guides/docker.md | 2 +- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/docs/deployment-self-hosting/core-configuration/initial-setup.md b/docs/docs/deployment-self-hosting/core-configuration/initial-setup.md index b8047cb47b07..e38453c16041 100644 --- a/docs/docs/deployment-self-hosting/core-configuration/initial-setup.md +++ b/docs/docs/deployment-self-hosting/core-configuration/initial-setup.md @@ -4,8 +4,9 @@ description: "How to initialise the instance and create the first superuser." sidebar_position: 10 --- -A new Flagsmith instance has no users. The first account you create is a superuser: it can manage the instance and sign -in to the Django Admin at `/admin/`. Pick one of the options below, depending on your installation. +A new Flagsmith instance has no users. The first account you create is a superuser: it can manage the instance and, once +[password login is enabled](/deployment-self-hosting/administration-and-maintenance/using-the-django-admin#authentication), +sign in to the Django Admin at `/admin/`. Pick one of the options below, depending on your installation. ## From the dashboard (recommended) diff --git a/docs/docs/deployment-self-hosting/hosting-guides/docker.md b/docs/docs/deployment-self-hosting/hosting-guides/docker.md index 0621571c8d88..cd698a96f010 100644 --- a/docs/docs/deployment-self-hosting/hosting-guides/docker.md +++ b/docs/docs/deployment-self-hosting/hosting-guides/docker.md @@ -49,7 +49,7 @@ The web user interface communicates via REST to the API that powers the applicat Once you have created an account and some flags, you can then start using the API with one of the [Flagsmith Client SDKs](https://github.com/Flagsmith?q=client&type=&language=). You will need to override the API endpoint for each SDK to point to [http://localhost:8000/api/v1/](http://localhost:8000/api/v1/). -You can access the Django Admin console to get CRUD access to some of the core tables within the API. The admin account you created on first run already has access. To create another superuser, run: +You can access the Django Admin console to get CRUD access to some of the core tables within the API. The admin account you created on first run is a superuser. To log in with its email and password, set `ENABLE_ADMIN_ACCESS_USER_PASS: 'true'` in the API's environment and restart; see [Using the Django Admin](/deployment-self-hosting/administration-and-maintenance/using-the-django-admin#authentication). To create another superuser, run: ```bash docker compose exec flagsmith flagsmith createsuperuser