docs: Deployment and self hosting (#5911)

Co-authored-by: htessaro <[email protected]>

Author: guiwrite

docs/docs/deployment-self-hosting/_category_.json

@@ -0,0 +1,5 @@
+{
+    "label": "Deployment and Self-hosting",
+    "collapsed": false,
+    "position": 20
+}

docs/docs/deployment-self-hosting/administration-and-maintenance/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Administration and Maintenance",
+  "position": 5
+}

docs/docs/deployment-self-hosting/administration-and-maintenance/troubleshooting.md

@@ -0,0 +1,21 @@
+---
+title: Troubleshooting
+sidebar_label: Troubleshooting
+sidebar_position: 90
+---
+
+Here are some common issues encountered when trying to set up Flagsmith in a self-hosted environment.
+
+## Health Checks
+
+If you are using health checks, make sure to use `/health` as the health-check endpoint for both the API and the frontend.
+
+## API and Database Connectivity
+
+The most common cause of issues when setting things up in AWS with an RDS database is missing Security Group permissions between the API application and the RDS database. You need to ensure that the attached security groups for ECS/Fargate/EC2 allow access to the RDS database. [AWS provide more detail about this here](https://aws.amazon.com/premiumsupport/knowledge-center/ecs-task-connect-rds-database/) and [here](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Overview.RDSSecurityGroups.html).
+
+Make sure you have a `DATABASE_URL` environment variable set within the API application.
+
+## Frontend > API DNS Setup
+
+If you are running the API and the frontend as separate applications, you need to make sure that the frontend is pointing to the API. Check the [Frontend environment variables](/deployment/hosting/locally-frontend#environment-variables), particularly `API_URL`.

docs/docs/deployment-self-hosting/administration-and-maintenance/upgrades-and-rollbacks.md

@@ -0,0 +1,82 @@
+---
+sidebar_label: Upgrades and Rollbacks
+title: Upgrades and Rollbacks
+sidebar_position: 2
+---
+
+# Rolling Back to a Previous Version of Flagsmith
+
+:::warning
+
+These steps may result in data loss in the scenario where new models or fields have been added to the database. We recommend taking a full backup of the database before completing the rollback.
+
+:::
+
+This page covers the process of rolling back to a previous version of Flagsmith. If you need to roll back to a previous version, you will need to ensure that the database is also rolled back to the correct state. In order to do this, you will need to unapply all the migrations that happened between the version that you want to roll back to and the one that you are rolling back from. The following steps explain how to do that.
+
+## Steps for v2.151.0 and Later
+
+1. Identify the date and time that you deployed the version that you want to roll back to.
+
+:::tip
+
+If you are unsure about when you completed the previous deployment, you can use the `django_migrations` table as a guide. If you query the table using the following query, you should see the migrations that have been applied (in descending order), grouped in batches corresponding to each deployment.
+
+```sql
+SELECT *
+FROM django_migrations
+ORDER BY applied DESC
+```
+
+:::
+
+2. Run the rollback command inside a Flagsmith API container running the _current_ version of Flagsmith:
+
+```bash
+python manage.py rollbackmigrationsafter "<datetime from step 1>"
+```
+
+3. Roll back the Flagsmith API to the desired version.
+
+## Steps for Versions Earlier Than v2.151.0
+
+If you are rolling back from a version earlier than v2.151.0, you will need to replace step 2 above with the following two steps.
+
+### Step 1: Generate Rollback Commands
+
+Replace the datetime in the query below with a datetime after the deployment of the version you want to roll back to, and before any subsequent deployments. Execute the subsequent query against the Flagsmith database.
+
+```sql {14} showLineNumbers
+select
+    concat('python manage.py migrate ',
+    app,
+    ' ',
+    case
+        when substring(name, 1, 4)::integer = 1 then 'zero'
+        else lpad((substring(name, 1, 4)::integer - 1)::text, 4, '0')
+        end
+    ) as "python_commands"
+from django_migrations
+where id in (
+    select min(id)
+    from django_migrations
+    where applied >= 'yyyy-MM-dd HH:mm:ss'
+    group by app
+);
+```
+
+Example output:
+
+```
+                python_commands
+-----------------------------------------------
+ python manage.py migrate multivariate 0007
+ python manage.py migrate segment 0004
+ python manage.py migrate environments 0034
+ python manage.py migrate features 0064
+ python manage.py migrate token_blacklist zero
+```
+
+### Step 2: Execute the Rollback Commands
+
+Run the generated commands inside a Flagsmith API container running the _current_ version of Flagsmith.

docs/docs/deployment-self-hosting/administration-and-maintenance/using-the-django-admin.md

@@ -0,0 +1,55 @@
+---
+sidebar_label: Django Admin
+title: Django Admin
+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.
+
+:::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.
+
+::: 
+
+## 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.
+
+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/hosting/locally-api#locally) from a Flagsmith API shell.
+* If no users exist yet, [visit the Initialise Config page](/deployment/hosting/locally-api#environments-with-no-direct-console-access-eg-heroku-ecs).
+* Manually set the `is_staff` and `is_superuser` database fields for your user in the `users_ffadminuser` table.
+
+## Authentication
+
+You can log in to Django Admin using the same email and password you use to log in to Flagsmith, or using Google login.
+
+### 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`.
+
+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/hosting/locally-api#email).
+* From a Flagsmith API shell, run `python manage.py changepassword [email protected]` 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.
+
+Set your Google OAuth client ID and secret in the following Flagsmith API environment variables:
+
+* `OAUTH_CLIENT_ID`
+* `OAUTH_CLIENT_SECRET`
+
+To log in with Google, click "Log in using SSO" from the Django Admin login page.

docs/docs/deployment-self-hosting/core-configuration/_category_.json

@@ -0,0 +1,7 @@
+{
+  "label": "Core Configuration",
+  "position": 30,
+  "link": {
+    "type": "generated-index"
+  }
+} 

docs/docs/deployment-self-hosting/core-configuration/caching-strategies.md

@@ -0,0 +1,42 @@
+---
+title: "Caching Strategies"
+description: "How to configure caching for API endpoints and the environment document."
+sidebar_position: 40
+---
+
+The application utilises an in-memory cache for a number of different API endpoints to improve performance. The main things that are cached are listed below:
+
+1. Environment flags - the application utilises an in memory cache for the flags returned when calling /flags. The number of seconds this is cached for is configurable using the environment variable `"CACHE_FLAGS_SECONDS"`
+2. Project segments - the application utilises an in memory cache for returning the segments for a given project. The number of seconds this is cached for is configurable using the environment variable `"CACHE_PROJECT_SEGMENTS_SECONDS"`.
+3. Flags and identities endpoint caching - the application provides the ability to cache the responses to the GET /flags and GET /identities endpoints. The application exposes the configuration to allow the caching to be handled in a manner chosen by the developer. The configuration options are explained in more detail below.
+4. Environment document - when making heavy use of the environment document, it is often wise to utilise caching to reduce the load on the database. Details are provided below.
+
+## Flags & Identities Endpoint Caching
+
+To enable caching on the flags and identities endpoints (GET requests only), you must set the following environment variables:
+
+| Environment Variable                                               | Description                                                                                                                    | Example value                                          | Default                                       |
+| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------ | --------------------------------------------- |
+| `FLAG_IDENTITY_CACHE_LOCATION`                                     | The location to cache the flags and identities endpoints. One of `default` or `redis`.                                         | `redis`                                                |                                               |
+| `FLAG_IDENTITY_CACHE_TTL_SECONDS`                                  | The number of seconds to cache the flags and identities endpoints for.                                                         | `60`                                                   | `0` (i.e. don't cache)                        |
+
+## Environment Document Caching
+
+To enable caching on the environment document endpoint, you must set the following environment variables:
+
+:::caution
+
+Persistent cache should only be used with cache backends that offer a centralised cache. It should not be used with e.g. LocMemCache.
+
+:::
+
+:::info
+
+When using a persistent cache, a change can take a few seconds to update the cache. This can also be optimised by increasing the performance of your task processor.
+
+:::
+
+| Environment Variable                  | Description                                                                                                                                                                                       | Example value                                          | Default                                       |
+|---------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------|-----------------------------------------------|
+| `CACHE_ENVIRONMENT_DOCUMENT_MODE`     | The caching mode. One of `PERSISTENT` or `EXPIRING`. Note that although the default is `EXPIRING` there is no caching by default due to the default value of `CACHE_ENVIRONMENT_DOCUMENT_SECONDS` | `PERSISTENT`                                           | `EXPIRING`                                    |
+| `CACHE_ENVIRONMENT_DOCUMENT_SECONDS`  | Number of seconds to cache the environment for (only relevant when `CACHE_ENVIRONMENT_DOCUMENT_MODE=EXPIRING`)                                                                                    | `60`                                                   | `0` ( = don't cache)                          | 

docs/docs/deployment-self-hosting/core-configuration/email-setup.md

@@ -0,0 +1,50 @@
+---
+title: "Email Setup"
+description: "How to configure Flagsmith to send emails using SMTP or SendGrid."
+sidebar_position: 30
+---
+
+:::note
+
+You can self-host Flagsmith without setting up an email server/gateway. You can invite additional users to the platform using invitation links, and the platform will run fine without email.
+
+:::
+
+:::tip
+
+Flagsmith makes use of the `django_site` table to provide the domain name for email template links. You will need to configure the record in this table to point to your domain for email links to work.
+
+:::
+
+## Required Environment Variables
+
+- `SENDER_EMAIL`: Email address from which emails are sent
+- `EMAIL_BACKEND`: One of:
+  - `django.core.mail.backends.smtp.EmailBackend`
+  - `sgbackend.SendGridBackend`
+  - `django_ses.SESBackend`
+
+## SMTP Configuration
+
+If using `django.core.mail.backends.smtp.EmailBackend`, you will need to configure:
+
+- `EMAIL_HOST` = env("EMAIL_HOST", default='localhost')
+- `EMAIL_HOST_USER` = env("EMAIL_HOST_USER", default=None)
+- `EMAIL_HOST_PASSWORD` = env("EMAIL_HOST_PASSWORD", default=None)
+- `EMAIL_PORT` = env("EMAIL_PORT", default=587)
+- `EMAIL_USE_TLS` = env.bool("EMAIL_USE_TLS", default=True)
+
+## SendGrid Configuration
+
+If using `sgbackend.SendGridBackend`, you will need to configure:
+
+- `SENDGRID_API_KEY`: API key for the SendGrid account
+
+## AWS SES Configuration
+
+If using AWS SES, you will need to configure:
+
+- `AWS_SES_REGION_NAME`: If using Amazon SES as the email provider, specify the region (e.g. eu-central-1) that contains your verified sender email address. Defaults to us-east-1
+- `AWS_SES_REGION_ENDPOINT`: SES region endpoint, e.g. email.eu-central-1.amazonaws.com. Required when using SES.
+- `AWS_ACCESS_KEY_ID`: If using Amazon SES, these form part of your SES credentials.
+- `AWS_SECRET_ACCESS_KEY`: If using Amazon SES, these form part of your SES credentials.