docs: add, refactor, and reformat discourse docs feat. charmcraft

common.mk

@@ -194,7 +194,7 @@ docs:  ## Build documentation
 
 .PHONY: docs-auto
 docs-auto:  ## Build and host docs with sphinx-autobuild
-	uv run --extra docs sphinx-autobuild -b html --open-browser --port=8080 --ignore *.kate-swp --ignore docs/reference/commands/** --watch $(PROJECT) $(DOCS) $(DOCS)/_build
+	uv run --extra docs sphinx-autobuild -b html --open-browser --port=8080 --ignore *.kate-swp --ignore docs/reference/commands/ --watch $(PROJECT) $(DOCS) $(DOCS)/_build
 
 .PHONY: pack-pip
 pack-pip:  ##- Build packages for pip (sdist, wheel)

docs/explanation/#index.rst#

@@ -0,0 +1,18 @@
+.. _explanation:
+
+Explanation
+***********
+
+As Charmcraft is a part of the `Juju Charm SDK <https://juju.is/docs/sdk>`_, most
+explanation is hosted on the `Charm SDK docs <https://juju.is/docs/sdk/explanation>`_.
+
+.. toctree::
+   :maxdepth: 1
+
+   /common/craft-parts/explanation/dump_plugin
+   /common/craft-parts/explanation/filesets
+   lifecycle
+
+
+`Charm SDK docs <https://juju.is/docs/sdk/explanation>`_
+========================================================

docs/explanation/index.rst

@@ -3,16 +3,4 @@
 Explanation
 ***********
 
-As Charmcraft is a part of the `Juju Charm SDK <https://juju.is/docs/sdk>`_, most
-explanation is hosted on the `Charm SDK docs <https://juju.is/docs/sdk/explanation>`_.
-
-.. toctree::
-   :maxdepth: 1
-
-   /common/craft-parts/explanation/dump_plugin
-   /common/craft-parts/explanation/filesets
-   lifecycle
-
-
-`Charm SDK docs <https://juju.is/docs/sdk/explanation>`_
-========================================================
+TBA

docs/howto/index.rst

@@ -1,11 +1,22 @@
-.. _howto:
-
-How-To
-******
+.. _how-to-guides:
+How-to guides
+=============
 
 .. toctree::
    :maxdepth: 2
 
-   charm-to-poetry
-   charm-to-python
-   shared-cache
+   Manage the charmcraft CLI <manage-the-charmcraft-cli>
+   Manage charms <manage-charms>
+   Manage charms (12-factor apps) <manage-12-factor-app-charms>
+   Manage extensions <manage-extensions>
+   Manage resources <manage-resources>
+   Manage libraries <manage-libraries>
+   Manage parts <manage-parts>
+   Manage the current Charmhub user <manage-the-current-charmhub-user>
+   Manage names <manage-names>
+   Manage revisions <manage-revisions>
+   Manage channels <manage-channels>
+   Manage tracks <manage-tracks>
+   Manage icons <manage-icons>
+   Misc <misc/index>
+   Manage bundles <manage-bundles>

docs/howto/manage-12-factor-app-charms.md

@@ -0,0 +1,259 @@
+(manage-12-factor-app-charms)=
+# How to manage 12-factor app charms
+
+
+<!--TODO: There are a few more low-hanging fruit topics that we can and should cover:
+
+When we create such sections we should include thinks at both the rock and the charm level (because the 12-Factor app app charm wants you to think about them in this coupled fashion). However, for the Rockcraft things, we should have those sections point to Rockcraft docs. For example:
+
+## Update the OCI image for a 12-Factor app charm
+
+See {ref}`Rockcraft Documentation > How to update the OCI image... <15018md>`
+
+-->
+
+> 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:
+
+```text
+charmcraft init --profile <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:
+
+```text
+charmcraft init --profile flask-framework
+```
+
+````
+
+````{dropdown} Example: Django application
+
+Specify the `django-framework` profile:
+
+```text
+charmcraft init --profile django-framework
+```
+
+````
+
+````{dropdown} Example: FastAPI application
+
+
+Specify the `fastapi-framework` profile:
+
+```text
+charmcraft init --profile fastapi-framework
+```
+
+````
+
+````{dropdown} Example: Go application
+
+Specify the `go-framework` profile:
+
+```text
+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`:
+
+```text
+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 <app name> token=<token>`.
+
+> See also: [How to add a configuration to a charm <how-to-add-a-configuration-option-to-a-charm>`, [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 <app name> token=<token>`.
+
+> See also: [How to add a configuration to a charm <how-to-add-a-configuration-option-to-a-charm>`
+```
+
+```{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 <app name> token=<token>`.
+
+> See also: [How to add a configuration to a charm <how-to-add-a-configuration-option-to-a-charm>`
+{ref}`/tab]
+
+```
+
+<!--In addition to the environment variable, the configuration is also available in the FastAPI variable `app.config` without the `APP_` prefix.-->
+
+```{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 <app name> token=<token>`.
+
+> See also: [How to add a configuration to a charm <how-to-add-a-configuration-option-to-a-charm>`
+```
+
+
+## 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:
+  <endpoint name>:
+    interface: <endpoint interface name>
+    optional: false
+```
+
+Here, `<endpoint name>` corresponds to the endpoint of the application with which you want the integration, and `<endpoint interface name>` is the endpoint schema to which this relation conforms. Both the `<endpoint name>` and `<endpoint interface name>` 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> <endpoint name>`. 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: {ref}`How to add an integration to a charm <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:
+```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:
+```
+juju add-secret my-api-token value=1234 othervalue=5678
+```
+The output from the previous command will look something like:
+```
+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:
+
+```
+juju grant-secret my-api-token <app name>
+```
+
+Add the Juju secret ID to the application:
+
+```
+juju config <app name> 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 <how-to-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 <how-to-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 <how-to-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 <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:
+
+```
+juju run <app name> create-superuser username=<username> email=<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 (i.e., 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.
+
+

docs/howto/manage-bundles.rst

@@ -0,0 +1,40 @@
+.. manage-charm-bundles:
+How to manage charm bundles
+===========================
+
+   See first: `Juju \| Bundle <https://juju.is/docs/juju/bundle>`__
+
+.. important::
+   Starting with 1 Jan 2025, bundles are being phased out.
+
+
+Create a bundle
+---------------
+
+To create a bundle, create a ``<bundle>.yaml`` file with your desired configuration.
+
+  See more: :ref:`file-bundle-yaml`
+
+.. tip::
+   If you don't want to start from scratch, export the contents of your model to a ``<bundle>.yaml`` file via ``juju export-bundle --filename <bundle>.yaml`` or download the ``<bundle>.yaml`` of an existing bundle from Charmhub. See more: `Juju \| How to compare and export the contents of a model to a bundle <https://juju.is/docs/juju/manage-models#heading--compare-and-export-the-contents-of-a-model-to-a-bundle>`_.
+
+
+Pack a bundle
+-------------
+
+To pack a bundle, in the directory where you have your ``bundle.yaml``
+file (and possibly other files, e.g., a ``README.md`` file), create a
+``charmcraft.yaml`` file suitable for a bundle (at the minimum:
+``type: bundle``), then run ``charmcraft pack`` to pack the bundle. The
+result is a ``.zip`` file.
+
+   See more: :ref:`ref_commands_pack`
+
+Publish a bundle on Charmhub
+----------------------------
+
+The process is identical to that for a simple charm except that, at the
+step where you register the name, for bundles the command is
+``register-bundle``.
+
+   See more: :ref:`publish-a-charm`