Set up a 12-Factor app rock

The following how-to guide provides instructions on initializing and configuring rocks for 12-factor apps.

Initialize a 12-factor app rock

Use rockcraft init and specify the relevant profile:

rockcraft init --profile <profile>

By default, Rockcraft initializes the project for Ubuntu 24.04 LTS. To initialize it for another base, add the --base option:

rockcraft init --profile <profile> --base ubuntu@26.04

Rockcraft automatically creates a rockcraft.yaml project file for the rock in your current directory. You will need to check the project file to verify that the rock’s name and description are correct.

rockcraft init --profile django-framework

For more information, see: init

Include extra files in the OCI image

The files included in the image by default depend on the extension. For the list of default files, see the “Included or excluded files” section of the reference page for your framework: Flask, FastAPI, Go and Spring Boot. The Django extension includes the whole Django project directory, except for the db.sqlite3 file. The Flask and FastAPI extensions include only the default files, unless none of them exist. List any other files your app needs, such as additional Python modules, in the prime key.

Note

Part names added by extensions vary by Ubuntu version. On Ubuntu 22.04 LTS and Ubuntu 24.04 LTS, write extension/part; on Ubuntu 26.04 LTS, write extension.part. For rocks with base: bare, follow the convention for the configured build-base.

For expressjs-framework, place the migration script in the application directory instead; see Database migration.

To change this list, add the following snippet to the project file:

rockcraft.yaml
parts:
  flask-framework/install-app:
    prime:
      - flask/app/.env
      - flask/app/app.py
      - flask/app/webapp
      - flask/app/templates
      - flask/app/static

Note the flask/app/ prefix that is required followed by the relative path to the project root.

rockcraft.yaml
parts:
  flask-framework.install-app:
    prime:
      - app/.env
      - app/app.py
      - app/webapp
      - app/templates
      - app/static

Note the app/ prefix that is required followed by the relative path to the project root.

Include additional debs in the OCI image

If your app requires debs – for example, to connect to a database – add the following snippet to the project file.

The Flask, Django and FastAPI frameworks use Debian packages, which work with Ubuntu bases. For rocks with base: bare, the extensions already lists slices, which are incompatible with Debian packages in a single stage-packages key. In such cases, list slices instead. For example, you’d list libpq5_libs instead of libpq-dev.

rockcraft.yaml
parts:
  flask-framework/dependencies:
    stage-packages:
      # list required packages or slices for your Flask application below.
      - libpq-dev
rockcraft.yaml
parts:
  flask-framework.dependencies:
    stage-packages:
      # list required packages or slices for your Flask application below.
      - libpq-dev

Override commands

The services key follows the Pebble layer specification and defines the entrypoint to your app. You can override the default service commands in rockcraft.yaml.

To override a service’s command, check the default service entrypoint generated by the extension by running rockcraft expand-extensions. For rocks built on Ubuntu 26.04 LTS or with the Spring Boot extension, this requires the experimental extensions to be enabled; see Extensions. Then, adapt the command to your needs and declare it in your project file. For example:

Output of rockcraft expand-extensions
# ...
services:
  flask:
    override: replace
    command: /bin/python3 -m gunicorn -c /flask/gunicorn.conf.py 'app:app' -k [ sync ]
    startup: enabled
    after:
      - statsd-exporter
    user: _daemon_

To limit the maximum number of pending connections in Gunicorn to 1024, add the following lines to your project file.

rockcraft.yaml
services:
  flask:
    command: /bin/python3 -m gunicorn -c /flask/gunicorn.conf.py 'app:app' --backlog 1024 -k [ sync ]
Output of rockcraft expand-extensions
# ...
services:
  flask:
    override: replace
    command: /bin/python3 -m gunicorn -c /var/lib/gunicorn/gunicorn.conf.py 'app:app' -k [ sync ]
    startup: enabled
    after:
      - statsd-exporter
    user: _daemon_

To limit the maximum number of pending connections in Gunicorn to 1024, add the following lines to your project file.

rockcraft.yaml
services:
  flask:
    command: /bin/python3 -m gunicorn -c /var/lib/gunicorn/gunicorn.conf.py 'app:app' --backlog 1024 -k [ sync ]