diff --git a/docs/howto/manage-a-12-factor-app-charm.md b/docs/howto/manage-a-12-factor-app-charm.md deleted file mode 100644 index 7781276f0..000000000 --- a/docs/howto/manage-a-12-factor-app-charm.md +++ /dev/null @@ -1,324 +0,0 @@ -(manage-a-12-factor-app-charm)= - -# Manage a 12-factor app charm - - - -> See also: [`juju` | 12-factor-app charms](https://juju.is/docs/juju/charmed-operator) - - -## Prepare an OCI image for a 12-factor app charm - -> See more: [`rockcraft` | Build a 12-factor app rock](https://documentation.ubuntu.com/rockcraft/en/latest/how-to/build-a-12-factor-app-rock/#include-extra-files-in-the-oci-image) - - -## Initialise a 12-factor app charm - -Use `charmcraft init` and specify the relevant profile: - -```bash -charmcraft init --profile -``` - -Charmcraft automatically creates `charmcraft.yaml`, `requirements.txt` and source code -for the charm in your current directory. You will need to check `charmcraft.yaml` and -`README.md` and verify that the charm's name and description are correct. - -> See also: {ref}`ref_commands_init` - -````{dropdown} Example: Flask application - -Specify the `flask-framework` profile: - -```bash -charmcraft init --profile flask-framework -``` - -```` - - -````{dropdown} Example: Django application - -Specify the `django-framework` profile: - -```bash -charmcraft init --profile django-framework -``` - -```` - - -````{dropdown} Example: FastAPI application - - -Specify the `fastapi-framework` profile: - -```bash -charmcraft init --profile fastapi-framework -``` - -```` - - -````{dropdown} Example: Go application - -Specify the `go-framework` profile: - -```bash -charmcraft init --profile go-framework -``` - -```` - - -## Manage configurations for a 12-factor app charm - -A charm configuration can be added if your 12-factor app requires environment variables, -for example, to pass a token for a service. Add the configuration in `charmcraft.yaml`: - -```yaml -config: - options: - token: - description: The token for the service. - type: string -``` - -```{dropdown} Flask application - -A user-defined configuration option will correspond to an environment variable generated -by the `paas-charm` project to expose the configuration to the Flask workload. In -general, a configuration option `config-option-name` will be mapped as -`FLASK_CONFIG_OPTION_NAME` where the option name will be converted to upper case, dashes -will be converted to underscores and the `FLASK_` prefix will be added. In the example -above, the `token` configuration will be mapped as the `FLASK_TOKEN` environment -variable. In addition to the environment variable, the configuration is also available -in the Flask variable `app.config` without the `FLASK_` prefix. - -The configuration can be set on the deployed charm using `juju config -token=`. - -> See also: [How to add a configuration to a charm](https://juju.is/docs/sdk/config), -> [Configuration Handling -- Flask -> Documentation](https://flask.palletsprojects.com/en/3.0.x/config/) -``` - -```{dropdown} Django application - -A user-defined configuration option will correspond to an environment variable generated -by the `paas-charm` project to expose the configuration to the Django workload. In -general, a configuration option `config-option-name` will be mapped as -`DJANGO_CONFIG_OPTION_NAME` where the option name will be converted to upper case, -dashes will be converted to underscores and the `DJANGO_` prefix will be added. In the -example above, the `token` configuration will be mapped as the `DJANGO_TOKEN` -environment variable. - -The configuration can be set on the deployed charm using `juju config -token=`. - -> See also: [How to add a configuration to a charm](https://juju.is/docs/sdk/config) -``` - -```{dropdown} FastAPI application - -A user-defined configuration option will correspond to an environment variable generated -by the `paas-charm` project to expose the configuration to the FastAPI workload. In -general, a configuration option `config-option-name` will be mapped as -`APP_CONFIG_OPTION_NAME` where the option name will be converted to upper case, dashes -will be converted to underscores and the `APP_` prefix will be added. In the example -above, the `token` configuration will be mapped as the `APP_TOKEN` environment variable. - -The configuration can be set on the deployed charm using `juju config -token=`. - -> See also: [How to add a configuration to a charm](https://juju.is/docs/sdk/config), -``` - - - -```{dropdown} Go application - -A user-defined configuration option will correspond to an environment variable generated -by the `paas-charm` project to expose the configuration to the Go workload. In general, -a configuration option `config-option-name` will be mapped as `APP_CONFIG_OPTION_NAME` -where the option name will be converted to upper case, dashes will be converted to -underscores and the `APP_` prefix will be added. In the example above, the `token` -configuration will be mapped as the `APP_TOKEN` environment variable. - -The configuration can be set on the deployed charm using `juju config -token=`. - -> See also: [How to add a configuration to a charm](https://juju.is/docs/sdk/config), -``` - - -## Manage relations for a 12-factor app charm - -A charm integration can be added to your charmed 12-factor app by providing the -integration and endpoint definition in `charmcraft.yaml`: - -```yaml -requires: - : - interface: - optional: false -``` - -Here, `` corresponds to the endpoint of the application with which you -want the integration, and `` is the endpoint schema to which -this relation conforms. Both the `` and `` must -coincide with the structs defined in that particular application's charm's -`charmcraft.yaml` file. The key `optional` with value `False` means that the charm will -get blocked and stop the services if the integration is not provided. - -You can provide the integration to your deployed 12-factor app using `juju integrate -<12-factor app charm> `. After the integration has been established, the -connection string and other configuration options will be available as environment -variables that you may use to configure your 12-factor application. - -For example, if you wish to integrate your 12-factor application with PostgreSQL -([machine](https://charmhub.io/postgresql) or [k8s](https://charmhub.io/postgresql-k8s) -charm), add the following endpoint definition to `charmcraft.yaml`: - -```yaml -requires: - postgresql: - interface: postgresql_client - optional: True -``` - -Provide the integration to your deployed 12-factor app with `juju integrate <12-factor -app charm> postgresql`. This integration creates the following environment variables you -may use to configure your 12-factor application: - -- `POSTGRESQL_DB_CONNECT_STRING` -- `POSTGRESQL_DB_SCHEME` -- `POSTGRESQL_DB_NETLOC` -- `POSTGRESQL_DB_PATH` -- `POSTGRESQL_DB_PARAMS` -- `POSTGRESQL_DB_QUERY` -- `POSTGRESQL_DB_FRAGMENT` -- `POSTGRESQL_DB_USERNAME` -- `POSTGRESQL_DB_PASSWORD` -- `POSTGRESQL_DB_HOSTNAME` -- `POSTGRESQL_DB_PORT` - -> See also: [How to add an integration to a -> charm](https://juju.is/docs/sdk/implement-integrations-in-a-charm) - - -## Manage secrets for a 12-factor app charm - -A user secret can be added to a charm and all the keys and values in the secret will be -exposed as environment variables. Add the secret configuration option in -`charmcraft.yaml`: - -```yaml -config: - options: - api-token: - type: secret - description: Secret needed to access some API secret information -``` - -Once the charm is deployed, you can add a Juju secret to the model: - -```bash -juju add-secret my-api-token value=1234 othervalue=5678 -``` - -The output from the previous command will look something like: - -```console -secret:cru00lvmp25c77qa0qrg -``` - -From the output of the previous command, you can get the Juju secret ID. -Grant the application access to view the value of the secret: - -```bash -juju grant-secret my-api-token -``` - -Add the Juju secret ID to the application: - -```bash -juju config api-token=secret:cru00lvmp25c77qa0qrg -``` - -```{dropdown} Flask application - -The following environment variables are available for the application: - -- `FLASK_API_TOKEN_VALUE: "1234"` -- `FLASK_API_TOKEN_OTHERVALUE: "5678"` - -> See also: [How to manage secrets](https://juju.is/docs/juju/manage-secrets) -``` - -```{dropdown} Django application - -The following environment variables are available for the application: - -- `DJANGO_API_TOKEN_VALUE: "1234"` -- `DJANGO_API_TOKEN_OTHERVALUE: "5678"` - -> See also: [How to manage secrets](https://juju.is/docs/juju/manage-secrets) -``` - -```{dropdown} FastAPI application - -The following environment variables are available for the application: - -- `APP_API_TOKEN_VALUE: "1234"` -- `APP_API_TOKEN_OTHERVALUE: "5678"` - -> See also: [How to manage secrets](https://juju.is/docs/juju/manage-secrets) -``` - -```{dropdown} Go application - -The following environment variables are available for the application: - -- `APP_API_TOKEN_VALUE: "1234"` -- `APP_API_TOKEN_OTHERVALUE: "5678"` - -> See also: [How to manage secrets](https://juju.is/docs/juju/manage-secrets) -``` - - -## Use 12-factor app charms - - -### (If your charm is a Django charm) Create an admin user - -Use the `create-superuser` action to create a new Django admin account: - -```bash -juju run create-superuser username= email= -``` - -You must provide the username and email address. - - -### (If your workload depends on a database) Migrate the database - -If your app depends on a database, it is common to run a database migration -script before app startup which, for example, creates or modifies tables. This -can be done by including the `migrate.sh` script in the root of your project. It -will be executed with the same environment variables and context as the 12-factor -app. - -If the migration script fails, it will retry upon `update-status`. The migration script -will run on every unit. The script is assumed to be idempotent (in other words, can be -run multiple times) and that it can be run on multiple units simultaneously without -issue. Handling multiple migration scripts that run concurrently can be achieved by, for -example, locking any tables during the migration. diff --git a/docs/howto/manage-a-12-factor-app-charm.rst b/docs/howto/manage-a-12-factor-app-charm.rst new file mode 100644 index 000000000..95f31299e --- /dev/null +++ b/docs/howto/manage-a-12-factor-app-charm.rst @@ -0,0 +1,330 @@ +.. _manage-a-12-factor-app-charm: + + +Manage a 12-factor app charm +============================ + + See also: :external+juju:ref:`Juju | Charm ` + + +Prepare an OCI image for a 12-factor app charm +---------------------------------------------- + + See more: + :external+rockcraft:doc:`Rockcraft | How to build a 12-factor app rock + ` + + +Initialise a 12-factor app charm +-------------------------------- + +Use ``charmcraft init`` and specify the relevant profile: + +.. code-block:: bash + + charmcraft init --profile + +Charmcraft automatically creates ``charmcraft.yaml``, +``requirements.txt`` and source code for the charm in your +current directory. You will need to check ``charmcraft.yaml`` +and ``README.md`` to verify that the charm's name and +description are correct. + + See also: :ref:`ref_commands_init` + +.. tabs:: + + .. group-tab:: Flask + + Specify the ``flask-framework`` profile: + + .. code-block:: bash + + charmcraft init --profile flask-framework + + .. group-tab:: Django + + Specify the ``django-framework`` profile: + + .. code-block:: bash + + charmcraft init --profile django-framework + + .. group-tab:: FastAPI + + Specify the ``fastapi-framework`` profile: + + .. code-block:: bash + + charmcraft init --profile fastapi-framework + + .. group-tab:: Go + + Specify the ``go-framework`` profile: + + .. code-block:: bash + + charmcraft init --profile go-framework + + +Manage configurations for a 12-factor app charm +----------------------------------------------- + +A charm configuration can be added if your 12-factor app +requires environment variables, for example, to pass a +token for a service. Add the configuration in ``charmcraft.yaml``: + +.. code-block:: yaml + + config: + options: + token: + description: The token for the service. + type: string + +.. tabs:: + + .. group-tab:: Flask + + A user-defined configuration option will correspond to + an environment variable generated by the ``paas-charm`` + project to expose the configuration to the Flask workload. + In general, a configuration option ``config-option-name`` + will be mapped as ``FLASK_CONFIG_OPTION_NAME`` where the + option name will be converted to upper case, dashes will be + converted to underscores and the ``FLASK_`` prefix will be + added. In the example above, the ``token`` configuration will + be mapped as the ``FLASK_TOKEN`` environment variable. In + addition to the environment variable, the configuration is + also available in the Flask variable ``app.config`` without + the ``FLASK_`` prefix. + + See also: + :external+ops:ref:`How to add configuration to a charm `, + `Configuration Handling -- + Flask Documentation `_ + + .. group-tab:: Django + + A user-defined configuration option will correspond to an + environment variable generated by the ``paas-charm`` project + to expose the configuration to the Django workload. In general, + a configuration option ``config-option-name`` will be mapped as + ``DJANGO_CONFIG_OPTION_NAME`` where the option name will be + converted to upper case, dashes will be converted to underscores + and the ``DJANGO_`` prefix will be added. In the example above, + the ``token`` configuration will be mapped as the ``DJANGO_TOKEN`` + environment variable. + + `How to add configuration to a charm `_ + + .. group-tab:: FastAPI + + A user-defined configuration option will correspond to an environment + variable generated by the ``paas-charm`` project to expose the + configuration to the FastAPI workload. In general, a configuration option + called ``config-option-name`` will be mapped as ``APP_CONFIG_OPTION_NAME`` + where the option name will be converted to upper case, dashes will be + converted to underscores and the ``APP_`` prefix will be added. In the + example above, the ``token`` configuration will be mapped as the + ``APP_TOKEN`` environment variable. + + `How to add configuration to a charm `_ + + .. group-tab:: Go + + A user-defined configuration option will correspond to an environment + variable generated by the ``paas-charm`` project to expose the + configuration to the Go workload. In general, a configuration option + ``config-option-name`` will be mapped as ``APP_CONFIG_OPTION_NAME`` + where the option name will be converted to upper case, dashes will be + converted to underscores and the ``APP_`` prefix will be added. In the + example above, the ``token`` configuration will be mapped as the + ``APP_TOKEN`` environment variable. + + `How to add configuration to a charm `_ + +The configuration can be set on the deployed charm using: + +.. code-block:: bash + + juju config token= + + +Manage relations for a 12-factor app charm +------------------------------------------ + +A charm integration can be added to your charmed 12-factor app by providing +the integration and endpoint definition in ``charmcraft.yaml``: + +.. code-block:: yaml + + requires: + : + interface: + optional: false + +Here, ```` corresponds to the endpoint of the application with which +you want the integration, and ```` is the endpoint schema +to which this relation conforms. Both the ```` and +```` must coincide with the structs defined in the +``charmcraft.yaml`` file of that particular application's charm. The key ``optional`` +with value ``False`` means that the charm will get blocked and stop the services if +the integration is not provided. + +You can provide the integration to your deployed 12-factor app using: + +.. code-block:: bash + + juju integrate + +After the integration has been established, the connection string and other +configuration options will be available as environment variables that you may +use to configure your 12-factor application. + +For example, if you wish to integrate your 12-factor application with PostgreSQL +(`machine `_ or +`k8s `_ +charm), add the following endpoint definition to ``charmcraft.yaml``: + +.. code-block:: yaml + + requires: + postgresql: + interface: postgresql_client + optional: True + +Provide the integration to your deployed 12-factor app with: + +.. code-block:: bash + + juju integrate postgresql + +This integration creates the following environment variables you may use to +configure your 12-factor application. + +- ``POSTGRESQL_DB_CONNECT_STRING`` +- ``POSTGRESQL_DB_SCHEME`` +- ``POSTGRESQL_DB_NETLOC`` +- ``POSTGRESQL_DB_PATH`` +- ``POSTGRESQL_DB_PARAMS`` +- ``POSTGRESQL_DB_QUERY`` +- ``POSTGRESQL_DB_FRAGMENT`` +- ``POSTGRESQL_DB_USERNAME`` +- ``POSTGRESQL_DB_PASSWORD`` +- ``POSTGRESQL_DB_HOSTNAME`` +- ``POSTGRESQL_DB_PORT`` + + See also: `How to add an integration to a charm + `_ + + +Manage secrets for a 12-factor app charm +---------------------------------------- + +A user secret can be added to a charm and all the keys and values +in the secret will be exposed as environment variables. Add the secret +configuration option in ``charmcraft.yaml``: + +.. code-block:: yaml + + config: + options: + api-token: + type: secret + description: Secret needed to access some API secret information + +Once the charm is deployed, you can add a juju secret to the model: + +.. terminal:: + :input: juju add-secret my-api-token value=1234 othervalue=5678 + + secret:cru00lvmp25c77qa0qrg + +From this output, you can get the Juju secret ID. Grant the application +access to view the value of the secret: + +.. code-block:: bash + + juju grant-secret my-api-token + +Add the Juju secret ID to the application: + +.. code-block:: bash + + juju config api-token=secret:cru00lvmp25c77qa0qrg + +.. tabs:: + + .. group-tab:: Flask + + The following environment variables are available for the application: + + - ``APP_API_TOKEN_VALUE: "1234"`` + - ``APP_API_TOKEN_OTHERVALUE: "5678"`` + + See also: `How to manage secrets + `_ + + + .. group-tab:: Django + + The following environment variables are available for the application: + + - ``DJANGO_API_TOKEN_VALUE: "1234"`` + - ``DJANGO_API_TOKEN_OTHERVALUE: "5678"`` + + See also: `How to manage secrets + `_ + + + .. group-tab:: FastAPI + + The following environment variables are available for the application: + + - ``APP_API_TOKEN_VALUE: "1234"`` + - ``APP_API_TOKEN_OTHERVALUE: "5678"`` + + See also: `How to manage secrets + `_ + + .. group-tab:: Go + + The following environment variables are available for the application: + + - ``APP_API_TOKEN_VALUE: "1234"`` + - ``APP_API_TOKEN_OTHERVALUE: "5678"`` + + See also: `How to manage secrets + `_ + + + +Use 12-factor app charms +------------------------ + + +(If your charm is a Django charm) Create an admin user +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use the ``create-superuser`` action to create a new Django admin account: + +.. code-block:: bash + + juju run create-superuser username= email= + + +(If your workload depends on a database) Migrate the database +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If your app depends on a database, it is common to run a database migration +script before app startup which, for example, creates or modifies tables. This +can be done by including the ``migrate.sh`` script in the root of your project. +It will be executed with the same environment variables and context as the +12-factor app. + +If the migration script fails, it will retry upon ``update-status``. The migration +script will run on every unit. The script is assumed to be idempotent (in other words, +can be run multiple times) and that it can be run on multiple units simultaneously +without issue. Handling multiple migration scripts that run concurrently +can be achieved by, for example, locking any tables during the migration. diff --git a/docs/reference/analyzers-and-linters.md b/docs/reference/analyzers-and-linters.md deleted file mode 100644 index 399fde955..000000000 --- a/docs/reference/analyzers-and-linters.md +++ /dev/null @@ -1,89 +0,0 @@ -(charmcraft-analyzers-and-linters)= - -# Analysers and linters - -The following are the different checks that Charmcraft will run explicitly (when the user executes its `analyse` method) or implicitly (when packing charms). - -Any linter or analysis can be set in [the config](https://juju.is/docs/sdk/charmcraft-config) to be excluded from the normal execution. Also note that if any linter ends in error it will block the charm packing (you can pack it anyway using the `--force` option). - -You can read more about these checks in the [Charmcraft Analyze Specification](https://discourse.charmhub.io/t/proposal-charmcraft-analyze/4792). - - -## Language attribute - -If through analysis, the charm can be detected as being a Python based charm, then language shall be set to `python`. If not, it shall be set to `unknown`. - -When working with Python, it is possible to only publish byte-code. By doing so, troubleshooting is a harder task. Charms with Python sources delivered are preferred. - -This attribute meets the requirements to be set to `python` when: - -- the charm has a text dispatch which executes a .py -- the charm has a .py entry point -- the entry point file is executable - -## Framework attribute - - -When using `ops`, it is best to import it from a common path and not make customisation or package forks from it. If `ops` code is detected in the charm sources, this attribute's value shall be set to `operator`. If not, the charm may be using the Reactive Framework, and in this case the attribute value will be `reactive`. Else, it shall be set to `unknown`. - -This check hint meets the requirements for `ops` when: - -- language attribute is set to `python` -- the charm contains `venv/ops` -- the charm imports `ops` in the entry point - -The requirements for the Reactive Framework are: - -...or the Reactive Framework is used, if the charm... - -- has a metadata.yaml with `name` in it -- has a `reactive/.py` file that imports `charms.reactive` -- has a file name that starts with `charms.reactive-` inside the `wheelhouse` directory - - -## Juju metadata linter - -This linter verifies that the `metadata.yaml` file exists and is sane. - -The charm is considered to have a valid metadata if the following checks are true: - -- the `metadata.yaml` is present -- it is a valid YAML file -- it has at least the following fields: `name`, `summary`, and `description` - - -## Juju actions linter - -*(new in 1.4)* - -This linter verifies that the `actions.yaml` file, if exists, is a valid YAML file. The file is optional. The file contents are not verified. - - -## Juju config linter - -*(new in 1.4)* - -This linter verifies that the `config.yaml` file, if exists, is valid. This file is optional. - -If the file exists, it is considered valid if the following checks are true: - -- it has the `options` key -- it is a dictionary -- each item inside has the mandatory `type` key - -Check how to [create config.yaml and configure charms](https://discourse.charmhub.io/t/creating-config-yaml-and-configuring-charms/1039) for more information. - - -## Charm entrypoint linter - -*(new in 2.1)* - -Check the entry point is correct. Note that even if most modern charms has a typical `src/charm.py` entry point, not all charms have one, as Juju has different ways to deliver its events. - -This linter validates that, if an entry point is called from the `dispatch` file, that entry point... - -- exists -- is a file -- is executable - -The entry point content is *not* validated. diff --git a/docs/reference/analyzers-and-linters.rst b/docs/reference/analyzers-and-linters.rst new file mode 100644 index 000000000..af83fe5fe --- /dev/null +++ b/docs/reference/analyzers-and-linters.rst @@ -0,0 +1,125 @@ +.. _charmcraft-analyzers-and-linters: + + +Analysers and linters +===================== + +The following are the different checks that Charmcraft will run +explicitly (when the user executes its ``analyse`` method) or implicitly +(when packing charms). + +Any linter or analysis can be set in the +`config `_ to be excluded +from the normal execution. Also note that if any linter ends in error it +will block the charm packing (you can pack it anyway using the +``--force`` option). + +You can read more about these checks in the `Charmcraft Analyze +Specification `_. + + +Language attribute +------------------ + +If through analysis, the charm can be detected as being a Python based +charm, then language shall be set to ``python``. If not, it shall be set +to ``unknown``. + +When working with Python, it is possible to only publish byte-code. By +doing so, troubleshooting is a harder task. Charms with Python sources +delivered are preferred. + +This attribute meets the requirements to be set to ``python`` when: + +- the charm has a text dispatch which executes a .py +- the charm has a .py entry point +- the entry point file is executable + + +Framework attribute +------------------- + +When using ``ops``, it is best to import it from a common path and not +make customisation or package forks from it. If ``ops`` code is detected +in the charm sources, this attribute's value shall be set to +``operator``. If not, the charm may be using the Reactive Framework, and +in this case the attribute value will be ``reactive``. Else, it shall be +set to ``unknown``. + +This check hint meets the requirements for ``ops`` when: + +- language attribute is set to ``python`` +- the charm contains ``venv/ops`` +- the charm imports ``ops`` in the entry point + +The requirements for the Reactive Framework are: + +…or the Reactive Framework is used, if the charm… + +- has a metadata.yaml with ``name`` in it +- has a ``reactive/.py`` file that imports ``charms.reactive`` +- has a file name that starts with ``charms.reactive-`` inside the + ``wheelhouse`` directory + + +Juju metadata linter +-------------------- + +This linter verifies that the ``metadata.yaml`` file exists and is sane. + +The charm is considered to have a valid metadata if the following checks +are true: + +- the ``metadata.yaml`` is present +- it is a valid YAML file +- it has at least the following fields: ``name``, ``summary``, and + ``description`` + + +Juju actions linter +------------------- + +*(new in 1.4)* + +This linter verifies that the ``actions.yaml`` file, if exists, is a +valid YAML file. The file is optional. The file contents are not +verified. + + +Juju config linter +------------------ + +*(new in 1.4)* + +This linter verifies that the ``config.yaml`` file, if exists, is valid. +This file is optional. + +If the file exists, it is considered valid if the following checks are +true: + +- it has the ``options`` key +- it is a dictionary +- each item inside has the mandatory ``type`` key + +Check how to `create config.yaml and configure charms +`_ +for more information. + + +Charm entrypoint linter +----------------------- + +*(new in 2.1)* + +Check the entry point is correct. Note that even if most modern charms +has a typical ``src/charm.py`` entry point, not all charms have one, as +Juju has different ways to deliver its events. + +This linter validates that, if an entry point is called from the +``dispatch`` file, that entry point… + +- exists +- is a file +- is executable + +The entry point content is *not* validated. diff --git a/docs/reference/extensions/django-framework-extension.md b/docs/reference/extensions/django-framework-extension.md deleted file mode 100644 index ba1450485..000000000 --- a/docs/reference/extensions/django-framework-extension.md +++ /dev/null @@ -1,236 +0,0 @@ -(django-framework-extension)= - -# Django framework extension - -The `django-framework` extension includes configuration options customised for a Django application. This document describes all the keys that a user may interact with. - -```{tip} -If you'd like to see the full contents contributed by this extension, see {ref}`How to manage extensions `. -``` - - -## Database requirement - -Django requires a database to function. When generating a new project, the default is to -make use of [SQLite](https://www.sqlite.org/). Using SQLite is not recommended for -production, especially on Kubernetes deployments, because the database is not shared -across units and any contents will be removed upon a new container being deployed. The -`django-framework` extension therefore requires a database integration for every -application, such as [PostgreSQL](https://www.postgresql.org/) or -[MySQL](https://www.mysql.com/). See the {ref}`how-to guide -` for how to deploy a database and integrate the -Django application with it. - - -## `config.options` key - -You can use the predefined options (run `charmcraft expand-extensions` for details) but also add your own, as needed. - -In the latter case, any option you define will be used to generate environment variables; a user-defined option `config-option-name` will generate an environment variable named `DJANGO_CONFIG_OPTION_NAME` where the option name is converted to upper case, dashes will be converted to underscores and the `DJANGO_` prefix will be added. - -In either case, you will be able to set it in the usual way by running `juju config