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

Info

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;

Installation Requirements

You must use a superuser-privileged user to install pgpodman.

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 &quot;pgpodman&quot;
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 postgres user.

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 &#39;postgres&#39;, cannot install into database &#39;differentdb&#39;

If you get this error, check your connection string to ensure that you are connecting to the postgres database as a superuser.

Launching Containers

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(&#39;-dt -p 5433:80/tcp -e PGADMIN_DEFAULT_EMAIL=&quot;craig.kerstiens@crunchydata.com&quot; -e PGADMIN_DEFAULT_PASSWORD=&quot;myVeryGoodPassword&quot; -e PGADMIN_LISTEN_PORT=80 docker.io/dpage/pgadmin4&#39;);

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

Next, -e is used to export each relevant environment variable needed to start the container:

PGADMIN_DEFAULT_EMAIL is the default email for the initial account in pgAdmin4
PGADMIN_DEFAULT_PASSWORD is the default password for the initial account in pgAdmin4
PGADMIN_LISTEN_PORT is 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:password@p.o7kabmt4wndjnp46exmkhvn634.db.postgresbridge.com:5432/myapp then you would find the pgAdmin4 app in your browser at the address http://p.o7kabmt4wndjnp46exmkhvn634.db.postgresbridge.com:5433.

Info

If 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_all parameter 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 list_containers().
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(&#39;f00dabcd1234&#39;);
WARNING: container &#39;f00dabcd1234&#39; 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 list_images().
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.

Getting Started with Container Apps