diff --git a/docs/howto/manage-channels.rst b/docs/howto/manage-channels.rst index 8e83b33d4..9ec11768d 100644 --- a/docs/howto/manage-channels.rst +++ b/docs/howto/manage-channels.rst @@ -12,36 +12,32 @@ When you register a name on Charmhub, that automatically creates 4 channels, all track ``latest`` but with different risk levels, namely, ``edge``, ``beta``, ``candidate``, ``stable``, respectively. - See more: :ref:`register-a-name` +See more: :ref:`register-a-name` -.. raw:: html +.. A charm channel consists of three pieces, in this order: //. - +.. Later on, if you specify a channel, you get: +.. - An implicit stable risk, if you don't declare a risk. +.. - An implicit empty branch, if you don't declare a branch. View the available channels --------------------------- @@ -57,6 +53,7 @@ The following output shows four channels, all of which have the same track, ``la but different risk levels, namely, ``edge``, ``beta``, ``candidate``, and ``stable``. .. terminal:: + :output-only: Track Channel Version Revision latest stable - - @@ -64,6 +61,7 @@ but different risk levels, namely, ``edge``, ``beta``, ``candidate``, and ``stab beta 0.1 1 edge ↑ ↑ +.. See more: :ref:`ref_commands_status` diff --git a/docs/howto/manage-charmcraft.rst b/docs/howto/manage-charmcraft.rst index 8cb1de6df..bb69d49db 100644 --- a/docs/howto/manage-charmcraft.rst +++ b/docs/howto/manage-charmcraft.rst @@ -53,21 +53,12 @@ to `these instructions `_). brew install charmcraft -.. terminal:: - - ==> Downloading https://ghcr.io/v2/homebrew/core/charmcraft/manifests/1.3.2 - ######################################################################## 100.0% - ==> Downloading https://ghcr.io/v2/homebrew/core/charmcraft/blobs/sha256:ebe7aac3dcfa401762faaf339a28e64bb5fb277a7d96bbcfb72bdc - ==> Downloading from https://pkg-containers.githubusercontent.com/ghcr1/blobs/sha256:ebe7aac3dcfa401762faaf339a28e64bb5fb277a7d - ######################################################################## 100.0% - ==> Pouring charmcraft--1.3.2.mojave.bottle.tar.gz - 🍺 /usr/local/Cellar/charmcraft/1.3.2: 2,205 files, 17.2MB - Charmhub commands work natively: -.. code-block:: bash +.. terminal:: charmcraft whoami + name: John Doe username: jdoe id: xxxxxxxxxxxxxxxxxxxxxxxxx @@ -76,12 +67,10 @@ In macOS, Charmcraft defaults to Multipass to build the charms in a container ma the target bases. Running pack asks to setup Multipass if not already installed, and continues with the packing process: -.. code-block:: bash - - $ charmcraft pack - .. terminal:: + charmcraft pack + Multipass is required, but not installed. Do you wish to install Multipass and configure it with the defaults? [y/N]: y ==> Downloading https://github.com/canonical/multipass/releases/download/v1.7.2/multipass-1.7.2+mac-Darwin.pkg Already downloaded: /Users/jdoe/Library/Caches/Homebrew/downloads/4237fcef800faa84459a2911c3818dfa76f1532d693b151438f1c8266318715b--multipass-1.7.2+mac-Darwin.pkg @@ -119,11 +108,16 @@ a fresh new VM with 4 cores, 8GB RAM and a 20GB disk and the name ‘charm-dev': Last, open a shell in your new Ubuntu virtual machine, and install Charmcraft there: -.. code-block:: bash +.. terminal:: multipass shell charm-dev - ... - ubuntu@charm-dev:~$ sudo snap install charmcraft --classic + +.. terminal:: + :user: ubuntu + :host: charm-dev + + sudo snap install charmcraft --classic + charmcraft 2.2.0 from Canonical✓ installed That's it. You can now start typing in Charmcraft commands. diff --git a/docs/howto/manage-charms.rst b/docs/howto/manage-charms.rst index 0c79442a6..b4a8098e5 100644 --- a/docs/howto/manage-charms.rst +++ b/docs/howto/manage-charms.rst @@ -544,24 +544,20 @@ is just a zip file with metadata and the operator code itself. Pack the charm: - .. code-block:: bash + .. terminal:: charmcraft pack - .. terminal:: - Created 'microsample-vm_ubuntu-22.04-amd64.charm'. Charms packed: microsample-vm_ubuntu-22.04-amd64.charm Optionally, verify that this has created a .charm file in your charm's root directory: - .. code-block:: bash + .. terminal:: ls - .. terminal:: - CONTRIBUTING.md charmcraft.yaml requirements.txt tox.ini LICENSE microsample-vm_ubuntu-22.04-amd64.charm src README.md pyproject.toml tests @@ -569,12 +565,10 @@ is just a zip file with metadata and the operator code itself. Optionally, verify that the .charm file is simply a zip file that contains everything you've packed plus any dependencies: - .. code-block:: bash + .. terminal:: unzip -l microsample-vm_ubuntu-22.04-amd64.charm | { head; tail;} - .. terminal:: - Archive: microsample-vm_ubuntu-22.04-amd64.charm Length Date Time Name --------- ---------- ----- ---- @@ -653,12 +647,10 @@ Publish a charm 3. Upload the charm to Charmhub: Use the ``charmcraft upload`` command followed by the your charm's path. E.g., if you are in the charm's root directory, - .. code-block:: bash + .. terminal:: charmcraft upload my-awesome-charm.charm - .. terminal:: - Revision 1 of my-awesome-charm created .. @@ -673,13 +665,10 @@ Publish a charm 4. If your charm has associated resources: These are not packed with the rest of the charm project, so you must upload them explicitly to Charmhub as well. For example: - .. code-block:: bash - - charmcraft upload-resource my-awesome-charm someresource - --filepath=/tmp/superdb.bin - .. terminal:: + charmcraft upload-resource my-awesome-charm someresource --filepath=/tmp/superdb.bin + Revision 1 created of resource 'someresource' for charm 'my-awesome-charm' .. @@ -695,13 +684,10 @@ Publish a charm target release channel. For a charm that has a resource, also specify the resource and its revision. E.g., - .. code-block:: bash - - charmcraft release my-awesome-charm --revision=1 --channel=beta - --resource someresource:1 - .. terminal:: + charmcraft release my-awesome-charm --revision=1 --channel=beta --resource someresource:1 + Revision 1 of charm 'my-awesome-charm' released to beta (attaching resources: 'someresource' r1) .. diff --git a/docs/howto/manage-extensions.rst b/docs/howto/manage-extensions.rst index 6bcdfa939..579ff5564 100644 --- a/docs/howto/manage-extensions.rst +++ b/docs/howto/manage-extensions.rst @@ -17,9 +17,10 @@ To view all the available Rockcraft or Charmcraft extensions, run the or :ref:`charmcraft list-extensions ` command. For example: -.. code-block:: bash +.. terminal:: + + charmcraft list-extensions - $ charmcraft list-extensions Extension name Supported bases Experimental bases --------------------- -------------------------- -------------------- django-framework ubuntu@22.04, ubuntu@24.04 ubuntu@26.04 @@ -40,71 +41,67 @@ extension. .. dropdown:: Example - .. code-block:: bash - - mkdir my-flask-app-k8s - cd my-flask-app-k8s/ - charmcraft init --profile flask-framework - - .. terminal:: + .. code-block:: bash - Charmed operator package file and directory tree initialised. + mkdir my-flask-app-k8s + cd my-flask-app-k8s/ + charmcraft init --profile flask-framework - Now edit the following package files to provide fundamental charm metadata - and other information: + .. terminal:: + :output-only: - charmcraft.yaml - src/charm.py - README.md + Charmed operator package file and directory tree initialised. - .. code-block:: bash + Now edit the following package files to provide fundamental charm metadata + and other information: - ls -R + charmcraft.yaml + src/charm.py + README.md - .. terminal:: + .. terminal:: - .: - charmcraft.yaml requirements.txt src + ls -R - ./src: - charm.py + .: + charmcraft.yaml requirements.txt src - .. code-block:: bash + ./src: + charm.py - cat charmcraft.yaml + .. code-block:: yaml + :caption: charmcraft.yaml - .. code-block:: yaml + name: my-flask-app-k8s - name: my-flask-app-k8s + type: charm - type: charm - - bases: - - build-on: - - name: ubuntu - channel: "22.04" - run-on: - - name: ubuntu - channel: "22.04" + bases: + - build-on: + - name: ubuntu + channel: "22.04" + run-on: + - name: ubuntu + channel: "22.04" - # (Required) - summary: A very short one-line summary of the flask application. + # (Required) + summary: A very short one-line summary of the flask application. - # (Required) - description: | - A comprehensive overview of your Flask application. + # (Required) + description: | + A comprehensive overview of your Flask application. - extensions: - - flask-framework + extensions: + - flask-framework - # Uncomment the integrations used by your application - # requires: - # mysql: - # interface: mysql_client - # limit: 1 - # postgresql: - # interface: postgresql_client - # limit: 1 + # Uncomment the integrations used by your application + # requires: + # mysql: + # interface: mysql_client + # limit: 1 + # postgresql: + # interface: postgresql_client + # limit: 1 To view details about what that extension is adding to your charm, set the ``CHARMCRAFT_ENABLE_EXPERIMENTAL_EXTENSIONS`` environment variable to ``1``, @@ -112,113 +109,112 @@ then run ``charmcraft expand-extensions``. For example: .. dropdown:: Expanding an extension - .. code-block:: bash - - CHARMCRAFT_ENABLE_EXPERIMENTAL_EXTENSIONS=1 charmcraft expand-extensions - - .. terminal:: - - *EXPERIMENTAL* extension 'flask-framework' enabled - name: my-flask-app-k8s - summary: A very short one-line summary of the flask application. - description: | - A comprehensive overview of your Flask application. - parts: - charm: - source: . - charm-entrypoint: src/charm.py - charm-binary-python-packages: [] - charm-python-packages: [] - charm-requirements: - - requirements.txt - charm-strict-dependencies: false - plugin: charm - type: charm - bases: - - build-on: - - name: ubuntu - channel: '22.04' - run-on: - - name: ubuntu - channel: '22.04' - actions: - rotate-secret-key: - description: Rotate the flask secret key. Users will be forced to log in again. - This might be useful if a security breach occurs. - assumes: - - k8s-api - containers: - flask-app: - resource: flask-app-image - peers: - secret-storage: - interface: secret-storage - provides: - metrics-endpoint: - interface: prometheus_scrape - grafana-dashboard: - interface: grafana_dashboard - requires: - logging: - interface: loki_push_api - ingress: - interface: ingress - limit: 1 - resources: - flask-app-image: - type: oci-image - description: flask application image. - config: - options: - webserver-keepalive: - type: int - description: Time in seconds for webserver to wait for requests on a Keep-Alive - connection. - webserver-threads: - type: int - description: Run each webserver worker with the specified number of threads. - webserver-timeout: - type: int - description: Time in seconds to kill and restart silent webserver workers. - webserver-workers: - type: int - description: The number of webserver worker processes for handling requests. - flask-application-root: - type: string - description: Path in which the application / web server is mounted. This configuration - will set the FLASK_APPLICATION_ROOT environment variable. Run app.config.from_prefixed_env() - in your Flask application in order to receive this configuration. - flask-debug: - type: boolean - description: Whether Flask debug mode is enabled. - flask-env: - type: string - description: What environment the Flask app is running in, by default it's 'production'. - flask-permanent-session-lifetime: - type: int - description: Time in seconds for the cookie to expire in the Flask application - permanent sessions. This configuration will set the FLASK_PERMANENT_SESSION_LIFETIME - environment variable. Run app.config.from_prefixed_env() in your Flask application - in order to receive this configuration. - flask-preferred-url-scheme: - type: string - default: HTTPS - description: Scheme for generating external URLs when not in a request context - in the Flask application. By default, it's "HTTPS". This configuration will - set the FLASK_PREFERRED_URL_SCHEME environment variable. Run app.config.from_prefixed_env() - in your Flask application in order to receive this configuration. - flask-secret-key: - type: string - description: The secret key used for securely signing the session cookie and - for any other security related needs by your Flask application. This configuration - will set the FLASK_SECRET_KEY environment variable. Run app.config.from_prefixed_env() - in your Flask application in order to receive this configuration. - flask-session-cookie-secure: - type: boolean - description: Set the secure attribute in the Flask application cookies. This - configuration will set the FLASK_SESSION_COOKIE_SECURE environment variable. - Run app.config.from_prefixed_env() in your Flask application in order to - receive this configuration. + .. terminal:: + + CHARMCRAFT_ENABLE_EXPERIMENTAL_EXTENSIONS=1 charmcraft expand-extensions + + + *EXPERIMENTAL* extension 'flask-framework' enabled + name: my-flask-app-k8s + summary: A very short one-line summary of the flask application. + description: | + A comprehensive overview of your Flask application. + parts: + charm: + source: . + charm-entrypoint: src/charm.py + charm-binary-python-packages: [] + charm-python-packages: [] + charm-requirements: + - requirements.txt + charm-strict-dependencies: false + plugin: charm + type: charm + bases: + - build-on: + - name: ubuntu + channel: '22.04' + run-on: + - name: ubuntu + channel: '22.04' + actions: + rotate-secret-key: + description: Rotate the flask secret key. Users will be forced to log in again. + This might be useful if a security breach occurs. + assumes: + - k8s-api + containers: + flask-app: + resource: flask-app-image + peers: + secret-storage: + interface: secret-storage + provides: + metrics-endpoint: + interface: prometheus_scrape + grafana-dashboard: + interface: grafana_dashboard + requires: + logging: + interface: loki_push_api + ingress: + interface: ingress + limit: 1 + resources: + flask-app-image: + type: oci-image + description: flask application image. + config: + options: + webserver-keepalive: + type: int + description: Time in seconds for webserver to wait for requests on a Keep-Alive + connection. + webserver-threads: + type: int + description: Run each webserver worker with the specified number of threads. + webserver-timeout: + type: int + description: Time in seconds to kill and restart silent webserver workers. + webserver-workers: + type: int + description: The number of webserver worker processes for handling requests. + flask-application-root: + type: string + description: Path in which the application / web server is mounted. This configuration + will set the FLASK_APPLICATION_ROOT environment variable. Run app.config.from_prefixed_env() + in your Flask application in order to receive this configuration. + flask-debug: + type: boolean + description: Whether Flask debug mode is enabled. + flask-env: + type: string + description: What environment the Flask app is running in, by default it's 'production'. + flask-permanent-session-lifetime: + type: int + description: Time in seconds for the cookie to expire in the Flask application + permanent sessions. This configuration will set the FLASK_PERMANENT_SESSION_LIFETIME + environment variable. Run app.config.from_prefixed_env() in your Flask application + in order to receive this configuration. + flask-preferred-url-scheme: + type: string + default: HTTPS + description: Scheme for generating external URLs when not in a request context + in the Flask application. By default, it's "HTTPS". This configuration will + set the FLASK_PREFERRED_URL_SCHEME environment variable. Run app.config.from_prefixed_env() + in your Flask application in order to receive this configuration. + flask-secret-key: + type: string + description: The secret key used for securely signing the session cookie and + for any other security related needs by your Flask application. This configuration + will set the FLASK_SECRET_KEY environment variable. Run app.config.from_prefixed_env() + in your Flask application in order to receive this configuration. + flask-session-cookie-secure: + type: boolean + description: Set the secure attribute in the Flask application cookies. This + configuration will set the FLASK_SESSION_COOKIE_SECURE environment variable. + Run app.config.from_prefixed_env() in your Flask application in order to + receive this configuration. To expand ``charmcraft.yaml`` using the extensions specified in the file and output the resulting configuration to the terminal, run diff --git a/docs/howto/manage-libraries.rst b/docs/howto/manage-libraries.rst index fcae0bee8..1cc165e88 100644 --- a/docs/howto/manage-libraries.rst +++ b/docs/howto/manage-libraries.rst @@ -90,14 +90,12 @@ The easiest way to find an existing library for a given charm is via will query Charmhub and show which libraries are published for the specified charm, along with API/patch versions. -.. code-block:: bash - - charmcraft list-lib blogsystem - .. terminal:: - Library name API Patch - superlib 1 0 + charmcraft list-lib blogsystem + + Library name API Patch + superlib 1 0 The listing will not show older API versions; this ensures that new users always start with the latest version. diff --git a/docs/howto/manage-resources.rst b/docs/howto/manage-resources.rst index bc1be58f6..a288ac66c 100644 --- a/docs/howto/manage-resources.rst +++ b/docs/howto/manage-resources.rst @@ -49,21 +49,17 @@ and ``--filepath=`` / ``--image=``. For exampl using the "short form" of the digest, the image needs to be present locally so its proper ID (the "long form") can be retrieved. -.. code-block:: bash - - charmcraft upload-resource my-super-charm someresource --filepath=/tmp/superdb.bin - .. terminal:: + charmcraft upload-resource my-super-charm someresource --filepath=/tmp/superdb.bin + Revision 1 created of resource 'someresource' for charm 'my-super-charm' -.. code-block:: bash +.. terminal:: charmcraft upload-resource my-super-charm redis-image --image=sha256:64aa8983ec5cea7bc143af18829836914fa405184d56dcbdfd9df672ade85249 -.. terminal:: - - Revision 1 created of resource 'redis-image' for charm 'my-super-charm' + Revision 1 created of resource 'redis-image' for charm 'my-super-charm' Charmcraft will first check if that specific image is available in Canonical's Registry, and just use it if that's the case. If not, it will try to get it from the developer's diff --git a/docs/howto/manage-revisions.rst b/docs/howto/manage-revisions.rst index eb668afc7..16dd02a9b 100644 --- a/docs/howto/manage-revisions.rst +++ b/docs/howto/manage-revisions.rst @@ -52,6 +52,7 @@ maintained separately from Charmcraft. ``3.6/candidate``.) .. terminal:: + :output-only: channels: | 5/stable: 117 2023-04-20 (117) 12MB amd64 ubuntu@22.04 @@ -72,12 +73,10 @@ To :ref:`ref_commands_release` a specific charm revision to a channel, run ``cha followed by the name of the charm and flags specifying the revision and its target channel. For example, -.. code-block:: bash +.. terminal:: charmcraft release my-awesome-charm --revision=1 --channel=beta -.. terminal:: - Revision 1 of charm 'my-awesome-charm' released to beta This opens the channel you're releasing to. For more information on diff --git a/docs/howto/manage-the-current-charmhub-user.rst b/docs/howto/manage-the-current-charmhub-user.rst index b911e2089..22bee245b 100644 --- a/docs/howto/manage-the-current-charmhub-user.rst +++ b/docs/howto/manage-the-current-charmhub-user.rst @@ -16,12 +16,10 @@ Local environments To log in to Charmhub, run :ref:`charmcraft login `: -.. code-block:: bash - - charmcraft login - .. terminal:: + charmcraft login + Opening an authorization web page in your browser. If it does not open, please open this URL: ... @@ -104,13 +102,10 @@ will push and release a charm could be: - Test that all is fine; for this get the content: - .. code-block:: bash - - CHARMCRAFT_AUTH=`cat test1` - charmcraft whoami - .. terminal:: + CHARMCRAFT_AUTH=`cat test1` charmcraft whoami + name: J. Doe username: jdoe-superdev id: VTLZAToLcdaIPtisVBjfiQYCXbpKwbCc @@ -126,11 +121,11 @@ will push and release a charm could be: CHARMCRAFT_AUTH with the content of ``secrets.auth`` file, and use Charmcraft as normal: - .. code-block:: bash + .. code-block:: bash - export CHARMCRAFT_AUTH= - ... - charmcraft upload my-super-charm.charm --release edge + export CHARMCRAFT_AUTH= + ... + charmcraft upload my-super-charm.charm --release edge Check the currently logged in user ---------------------------------- diff --git a/docs/howto/manage-web-app-charms/configure-web-app-charm.rst b/docs/howto/manage-web-app-charms/configure-web-app-charm.rst index 2d3094ca6..1ac6e449c 100644 --- a/docs/howto/manage-web-app-charms/configure-web-app-charm.rst +++ b/docs/howto/manage-web-app-charms/configure-web-app-charm.rst @@ -417,21 +417,22 @@ simultaneous requests with curl: .. code:: bash - curl --parallel --parallel-immediate --resolve flask-async-app:80:127.0.0.1 \ - http://flask-async-app/io http://flask-async-app/io http://flask-async-app/io \ - http://flask-async-app/io http://flask-async-app/io + curl --parallel --parallel-immediate --resolve flask-async-app:80:127.0.0.1 \ + http://flask-async-app/io http://flask-async-app/io http://flask-async-app/io \ + http://flask-async-app/io http://flask-async-app/io and they will all return at the same time. The results should arrive simultaneously and contain five instances of ``ok``: .. terminal:: + :output-only: - ok - ok - ok - ok - ok + ok + ok + ok + ok + ok It can take up to a minute for the configuration to take effect. When the configuration changes, the charm will re-enter the active state, which you diff --git a/docs/howto/manage-web-app-charms/use-web-app-charm.rst b/docs/howto/manage-web-app-charms/use-web-app-charm.rst index 89dd0897e..b60548743 100644 --- a/docs/howto/manage-web-app-charms/use-web-app-charm.rst +++ b/docs/howto/manage-web-app-charms/use-web-app-charm.rst @@ -702,6 +702,7 @@ From the list of URLs, look for the endpoint that contains a ``grafana`` suffix. This URL has the format: .. terminal:: + :output-only: http:///-grafana diff --git a/docs/howto/pack-a-hooks-based-charm-with-charmcraft.rst b/docs/howto/pack-a-hooks-based-charm-with-charmcraft.rst index d034d2c0f..70501851b 100644 --- a/docs/howto/pack-a-hooks-based-charm-with-charmcraft.rst +++ b/docs/howto/pack-a-hooks-based-charm-with-charmcraft.rst @@ -53,6 +53,7 @@ After this, you can pack your charm with ``charmcraft pack``, as usual: If successful, the result should look like the following. .. terminal:: + :output-only: Charms packed: tiny-bash_ubuntu-20.04-amd64.charm @@ -60,12 +61,10 @@ If successful, the result should look like the following. The charm file should contain all the files listed in the ``prime`` section of the ``tiny-bash`` part and the charm manifest. -.. code-block:: bash +.. terminal:: unzip -l tiny-bash_ubuntu-20.04-amd64.charm -.. terminal:: - Archive: tiny-bash_ubuntu-20.04-amd64.charm Length Date Time Name --------- ---------- ----- ---- @@ -90,24 +89,20 @@ The charm file should contain all the files listed in the ``prime`` section of t And you can also deploy your application with ``juju deploy``, as usual: -.. code-block:: bash - - juju deploy ./tiny-bash_ubuntu-20.04-amd64.charm - .. terminal:: + juju deploy ./tiny-bash_ubuntu-20.04-amd64.charm + Located local charm "tiny-bash", revision 0 Deploying "tiny-bash" from local charm "tiny-bash", revision 0 If successful, the result should look as below, i.e., with the application status active. -.. code-block:: bash +.. terminal:: juju status -.. terminal:: - Model Controller Cloud/Region Version SLA Timestamp default localhost-localhost localhost/localhost 2.9.12 unsupported 17:23:23-03:00