Container apps

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.

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 set up 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 "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 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 '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.

Launching containers

Once you've set up 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 --privileged docker.io/dpage/pgadmin4');

The above command has three key elements.

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

  2. -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.
  1. 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 is:

postgres://user:[email protected]: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 cluster 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.

Cluster maintenance and 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.

Common use cases for container apps with Postgres

We see three common use cases for Container Apps with Postgres on Crunchy Bridge:

  1. Turnkey apps on top of Postgres databases (examples include pg_tileserv,PostGraphile, PostgREST)
  2. Data reporting and visualization apps on top of your data (examples include pgAdmin 4 and Blazer)
  3. 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.

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('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 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.

Available ports

Currently Container Apps within Crunchy Bridge exposes 10 ports to you to launch containers on during the public beta. Ports 5433 to 5442 are available to be exposed to the public internet.

Limits

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.

Quickstart guides

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.

Database admin and browser apps

Turnkey APIs and apps

Database monitoring tools

Pages in this section: