Container Apps allow 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 your feedback with us as we progress towards making it generally available.
Container Apps is powered by a Crunchy Data extension named
Running a container process on your DB server is a privileged operation, and therefore this extension can only be installed into the
postgres database by the
postgres user (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.
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 three key elements.
-p 5433:80/tcpexposes 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,
-eis 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.
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
For example, if your database connection string is:
then you would find the pgAdmin4 app in your browser at the address:
If you run multiple containers on the same cluster host, they must each use a different public port. You can map any of the 10 ports from
5442 to your Container Apps.
Container Apps will persist during a maintenance event, failover, or resize. The
pgpodman extension will look at the
pgpodman_status table every 10 minutes to see what containers should be running and will start the container if it's not running.
We see three common use cases for Container Apps with Postgres on Crunchy Bridge:
- Turnkey apps on top of Postgres databases (examples include
- 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)
We have a collection of recipes to help get you up and running, but you're not limited to these examples. Any public docker image can be run in a container. If you find that some are particularly great for Container Apps on Crunchy Bridge, please reach out to Support and we can explore adding it to our examples.
pgpodman extension has a few other pieces included to help when working with Container Apps on Crunchy Bridge. The functions supported with
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.
We've created a number of examples, listed below, 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.