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>

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 following files are included in the image by default from the root of the project:

  • app (does not apply to the go-framework)

  • app.py (does not apply to the go-framework)

  • migrate

  • migrate.sh

  • migrate.py (does not apply to the go-framework)

  • static

  • templates

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 and higher, 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:

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. 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 ]