Getting Started with Container Apps
Container Apps allows you to launch and run a container from directly within Postgres. Container Apps is currently in public beta on Crunchy Bridge. During public beta you may find issues and areas of possible improvement. We welcome you to share all feedback with us as we progress towards making it generally available.
Getting started with Container Apps in Postgres
Container Apps is powered by a Crunchy Data extension named
ℹ️ InfoRunning a container process on your DB server is a privileged operation, and therefore this extension can only be installed into the
postgresdatabase by the
postgresuser (or another account with superuser privileges).
You can setup your database with the extension by running:
CREATE EXTENSION pgpodman;
You must use a superuser-privileged user to install
Attempting to install this extension when the connected user doesn’t have superuser privileges will produce the following error:
ERROR: permission denied to create extension "pgpodman" HINT: Must be superuser to create this extension.
This may happen if you connect as the
application user, or as any other non-superuser role. To fix this, check your connection string to ensure that you are connecting as a superuser such as the default
You must install
pgpodman into the
postgres database in your cluster.
Attempting to install this extension to a database other than
postgres (such as an application database) will produce the following error:
ERROR: pgpodman.dbname is set to 'postgres', cannot install into database 'differentdb'
If you get this error, check your connection string to ensure that you are connecting to the
postgres database as a superuser.
If your container exposes data from a specific database, you can call any database in the actual select statement when you create the container.
Once you’ve setup the extension you can launch your first container. As an example, here’s how you could launch pgAdmin4 directly from within Postgres:
SELECT run_container('-dt -p 5433:80/tcp -e PGADMIN_DEFAULT_EMAIL="[email protected]" -e PGADMIN_DEFAULT_PASSWORD="myVeryGoodPassword" -e PGADMIN_LISTEN_PORT=80 docker.io/dpage/pgadmin4');
The above command has a few key pieces.
-p 5433:80/tcp exposes the docker image to the public port (in this case, 5433) and routes it to the port the docker image is listening on (in this case, 80).
-e is used to export each relevant environment variable needed to start the container:
PGADMIN_DEFAULT_EMAILis the default email for the initial account in pgAdmin4
PGADMIN_DEFAULT_PASSWORDis the default password for the initial account in pgAdmin4
PGADMIN_LISTEN_PORTis the port which the pgAdmin4 web application will start up on. This needs to match the second port in our earlier config.
The final value,
docker.io/dpage/pgadmin4, specifies the docker image you want to launch.
After starting the Container App with the command above, the pgAdmin4 app would be running on the hostname of the connection string at port 5433. For example, if your database connection string was
postgres://user:[email protected]:5432/myapp then you would find the pgAdmin4 app in your browser at the address
ℹ️ InfoIf you run multiple containers on the same DB host, they must each use a different public port. You can map any of the 10 ports from 5433 to 5442 to your Container Apps.
Common use cases for Container Apps with Postgres
We see three common use cases for Container Apps with Postgres on Crunchy Bridge:
- Turnkey apps on top of Postgres databases (examples include
pg_tileserv, PostGraphile, PostgREST)
- Data reporting and visualization apps on top of your data (examples include pgAdmin 4 and Blazer)
- Running database monitoring agents right along side your instance (examples include Datadog, New Relic, pganalyze)
For many of the above we have a collection of recipes to help get you up and running with examples, but you’re not limited to just the examples above. Any public docker image can be run, if you feel some are particularly great for Container Apps on Crunchy Bridge please reach out and we can explore adding it to our examples.
More with pgpodman
The pgpodman extension has a few other pieces included to help when working with Container Apps on Crunchy Bridge. The functions supported with pgpodman include:
SELECT run_container(<podman_options>)- Start a container within your database.
SELECT list_containers(show_all boolean)- List all containers and status. By default assumes a false flag. With
show_allparameter as false it will list only running containers, true will list all containers both running and stopped.
SELECT list_containers_json(show_all boolean)- JSON-formatted output of
SELECT stop_container(<container_id>)- Stop a running container, but leaves it on the filesystem.
SELECT start_container(<container_id>)- Starts a container that is currently in a stopped state.
SELECT container_status(<container_id>)- Show status of a container.
SELECT container_logs(<container_id>)- Show the logs from a container.
SELECT remove_container(<container_id>)- Remove a stopped container from the container list. The container must have been stopped using
SELECT stop_container(<container_id>)first, or you’ll receive an error similar to this:
# SELECT remove_container('f00dabcd1234'); WARNING: container 'f00dabcd1234' does not exist or is still running
SELECT is_container_running(<container_id>)- Returns true if the given container is currently running.
SELECT list_images()- List all currently downloaded images.
SELECT list_images_json()- JSON-formatted output of
SELECT pull_image(<image_name>)- Downloads, but does not run, the indicated image.
SELECT remove_image(<image_id>)- Deletes the image from the local image cache.
SELECT pgpodman_version()- Returns a version string with the currently loaded extension library (pgpodman.so) version number, and the version of the podman executable program.
Currently Container Apps within Crunchy Bridge exposes 10 ports to you to launch containers on during the public beta. Ports
5442 are available to be exposed to the public internet.
Currently the filesystem is restricted to 2 GB of containers. In order effectively manage the size of containers we recommend
remove_container to free up space after stopping a container.
There are a number of examples we’ve provided within our docs to help you get started. If an example app you’re looking for isn’t here, give it a try and let us know if you need any help.