Docker for PostgreSQL¶

EPSIO PRIVATE PREVIEW

At this time, Epsio running in "standalone docker mode" is only available in private preview.
To get early access, contact us at support@epsio.io

DEVELOPMENT ENVIRONMENTS ONLY

Running Epsio on Docker is recommended only for development environments, not production use.

This guide will walk you through the process of deploying Epsio.

Before you begin¶

Before proceeding with the deployment guide, ensure that you have the following:

A Linux/Macbook machine to run epsio on with:
- Network access to your PostgreSQL instance.
- docker installed on it
A PostgreSQL Database with version 10+.

1. Prepare your database for Epsio¶

Open a connection to your database and follow the steps below.

Create a database user for Epsio's exclusive use:

CREATE USER epsio_user WITH PASSWORD '<password>';

Create a schema for Epsio

CREATE SCHEMA IF NOT EXISTS epsio;
GRANT CREATE, USAGE ON SCHEMA epsio TO epsio_user;
GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA epsio TO epsio_user;

Grant user permissions
Grant the epsio_user read-only access to all tables in your schema by running the following commands:

GRANT SELECT ON ALL TABLES IN SCHEMA public TO epsio_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO epsio_user;
GRANT CREATE, USAGE ON SCHEMA public TO epsio_user;

If you plan to access schemas other than the public schema, you'll need to run these commands for each schema.
Replace public with the name of your schema.

2. Configure logical replication¶

2.1 Check if logical replication is enabled¶

Run the following command to check if your PostgreSQL is already configured with logical replication:

postgres=> SHOW wal_level;
 wal_level 
-----------
 replica
(1 row)

If the result is logical, it means that logical replication is enabled, skip to set up replication.
If not, follow the steps below to enable logical replication.

2.2 Enable logical replication¶

To enable logical replication in a PostgreSQL database, you need to set the wal_level parameter in your database configuration to logical. For standard PostgreSQL installations, you can do this by either:

Method 1: Adding a wal_level = logical line to the postgresql.conf file.
Method 2: Running ALTER SYSTEM SET wal_level = logical;

Optional: Set the max_slot_wal_keep_size parameter to 4096 to limit the amount of WAL data that is retained for logical replication slots. (Postgres 13+)

Restart your database for the changes to take effect.

Verify that the wal_level parameter is set to "logical".

SHOW wal_level;
    wal_level
-------------------------
    logical
    (1 row)

2.3 Set up replication¶

Next, you'll need to set up replication by running the following commands in your database:

CREATE PUBLICATION epsio_publication;
CREATE PUBLICATION epsio_command_publication;

ALTER USER epsio_user WITH REPLICATION;

4. Run Epsio docker¶

Once finished, run the following command to run the standalone Epsio docker.

ACCOUNT_TOKEN - Your account's access token which can be retrieved from the cloud console settings page.
EPSIO_VERSION - The version of Epsio (see the changelog for the latest version information).

docker run --name epsio \
  -v <data_directory>:/var/lib/epsio \
  -e ACCOUNT_TOKEN='<ACCOUNT_TOKEN>' \
  -e DB_HOST='<DB_HOST>' \
  -e DB_NAME='<DB_NAME>' \
  -e DB_PASSWORD='<EPSIO_USER_PASSWORD>' \
  -e DB_PORT=<DB_PORT> \
  -e SOURCE_DATABASE_TYPE='postgres' \
   us-docker.pkg.dev/epsio-io/public/epsio:<EPSIO_VERSION>

Congratulations! You've successfully enabled replication in your database.

You are set to go and can create your first view. Visit the create_view for further details.

Troubleshooting¶

To troubleshoot, first check the docker logs:

docker logs epsio

If the above don't prove helpful, Run the following commands:

docker exec -it epsio dump-logs -o /tmp/diagnostic_dump
docker cp epsio:/tmp/diagnostic_dump <output file path>

And send the outputed file to Epsio support