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 25374a50dc60..b995f50b76a9 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..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,25 +4,59 @@ 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, 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. -## 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..cd698a96f010 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 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 -# 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