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
rockcraft init --profile expressjs-framework
rockcraft init --profile fastapi-framework
rockcraft init --profile flask-framework
rockcraft init --profile go-framework
rockcraft init --profile spring-boot-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:
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.
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.
N/A
The entire app directory is copied into the rock, except for the
files left out by the files array in package.json or by a
.npmignore file. Place any additional files in the app
directory.
The entire directory containing the package.json file is copied
into the rock, except for the files left out by the files array
in package.json or by a .npmignore file. Place any
additional files in the same directory as package.json. If the
app has a build script, the dist directory is always included.
parts:
fastapi-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.
parts:
fastapi-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.
parts:
go-framework/assets:
stage:
- app/templates
- app/static
- app/migrate.sh
Note the app/ prefix that is required followed by the relative
path to the project root.
parts:
go-framework.assets:
stage:
- app/templates
- app/static
- app/migrate.sh
Note the app/ prefix that is required followed by the relative
path to the project root.
parts:
spring-boot-framework/assets:
stage:
- app/migrate.sh
- app/another_file_or_directory
The app/ prefix is required for files in the stage key, followed by the relative
path to the project root.
parts:
spring-boot-framework.assets:
stage:
- app/migrate.sh
- app/another_file_or_directory
The app/ prefix is required for files in the stage key, 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.
parts:
django-framework/dependencies:
stage-packages:
# list required packages or slices for your Django application below.
- libpq-dev
parts:
django-framework.dependencies:
stage-packages:
# list required packages or slices for your Django application below.
- libpq-dev
parts:
fastapi-framework/dependencies:
stage-packages:
# list required packages or slices for your FastAPI application below.
- libpq-dev
parts:
fastapi-framework.dependencies:
stage-packages:
# list required packages or slices for your FastAPI application below.
- libpq-dev
parts:
runtime-debs:
plugin: nil
stage-packages:
- postgresql-client
For the go-framework extension, a deb could be needed for example to use an external command in the migration process.
The extension doesn’t provide a dedicated part for additional packages. Add your own part instead:
parts:
runtime-debs:
plugin: nil
stage-packages:
- postgresql-client
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:
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.
services:
flask:
command: /bin/python3 -m gunicorn -c /flask/gunicorn.conf.py 'app:app' --backlog 1024 -k [ sync ]
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.
services:
flask:
command: /bin/python3 -m gunicorn -c /var/lib/gunicorn/gunicorn.conf.py 'app:app' --backlog 1024 -k [ sync ]
rockcraft expand-extensions¶# ...
services:
django:
override: replace
command: /bin/python3 -m gunicorn -c /django/gunicorn.conf.py 'django_hello_world.wsgi:application' -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 rockcraft.yaml.
services:
django:
command: /bin/python3 -m gunicorn -c /django/gunicorn.conf.py 'django_hello_world.wsgi:application' --backlog 1024 -k [ sync ]
rockcraft expand-extensions¶# ...
services:
django:
override: replace
command: /bin/python3 -m gunicorn -c /var/lib/gunicorn/gunicorn.conf.py 'django_hello_world.wsgi:application' -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 rockcraft.yaml.
services:
django:
command: /bin/python3 -m gunicorn -c /var/lib/gunicorn/gunicorn.conf.py 'django_hello_world.wsgi:application' --backlog 1024 -k [ sync ]
rockcraft expand-extensions¶# ...
services:
fastapi:
override: replace
command: /bin/python3 -m uvicorn app:app
startup: enabled
environment:
UVICORN_HOST: 0.0.0.0
user: _daemon_
working-dir: /app
To limit the maximum number of pending connections in uvicorn to 1024, add the following
lines to rockcraft.yaml.
services:
fastapi:
command: /bin/python3 -m uvicorn app:app --backlog 1024
rockcraft expand-extensions¶# ...
services:
go:
override: replace
command: go-hello-world
startup: enabled
user: _daemon_
working-dir: /app
To pass the argument --example-arg to the main Go app, add the following lines
to rockcraft.yaml.
services:
go:
override: replace
command: go-hello-world --example-arg
rockcraft expand-extensions¶# ...
services:
expressjs:
override: replace
command: npm start
startup: enabled
environment:
NODE_ENV: production
user: _daemon_
working-dir: /app
To pass the argument --example-arg to the ExpressJS script, add the following lines
to rockcraft.yaml.
services:
expressjs:
command: npm start -- --example-arg
rockcraft expand-extensions¶# ...
services:
spring-boot:
override: replace
command: bash -c "java -jar *.jar"
startup: enabled
user: _daemon_
working-dir: /app
To enable a debug mode with a flag, add the following lines to rockcraft.yaml.
services:
spring-boot:
command: bash -c "java -jar *.jar --debug"