Install Promscale using a pre-built Docker container

Docker images for the Promscale Connector and TimescaleDB (with the Promscale extension) are available on Docker Hub.

If you are upgrading from the previously used Alpine image follow these upgrade instructions at the end of this page.

The TimescaleDB images have a suffix that indicates the version of PostgreSQL and TimescaleDB. For example, the tag pg14.2-ts2.6.1-latest includes PostgreSQL 14.2and TimescaleDB 2.6.1. pg14-latest is the latest image available for PostgreSQL version 14. Reference the appropriate images when deploying Promscale and follow the instructions provided by your container platform. If you are using Kubernetes follow these instructions instead.

important

Running Promscale directly using docker run is not recommended for production environments. This can be useful for testing purposes and is just provided as an example.

Install Promscale with Docker

Before you begin, you must have Docker installed on your local system. For packages and instructions, see the Docker installation documentation.

Installing Promscale using Docker run

Use Docker to create a network for Promscale and TimescaleDB:
```
docker network create --driver bridge promscale
```

Install TimescaleDB in a Docker container on a network named promscale. It also port forwards to port 5432 on your local system:

docker run --name timescaledb -e POSTGRES_PASSWORD=<password> \
-d -p 5432:5432 \
--network promscale \
timescale/timescaledb-ha:pg14-latest \
postgres -csynchronous_commit=off

Run the Promscale Connector Docker container on a network named promscale. It also port forwards to port 9201 on your local system:

docker run --name promscale -d -p 9201:9201 \
--network promscale timescale/promscale:latest \
-db.password=<password> \
-db.port=5432 \
-db.name=postgres \
-db.host=timescaledb \
-db.ssl-mode=allow

After you have installed Promscale, you can ingest data. For instructions, see the send data section.

Upgrading from the previous alpine image

Previously, our recommended image was located at timescaledev/promscale-extension. It was based on the Alpine docker image for PostgreSQL. Because of collation bugs and other issues we have now switched our recommendation to the Debian-based image above.

Our previous Alpine-based image will continue to be updated and supported until the end of 2022 but we encourage users to migrate to the timescale/timescaledb-ha. All new installations should switch to the timescale/timescaledb-haimage.

You can also migrate to Debian version by doing the following (please note: this can be a lengthy process and involves downtime):

Use docker inspect to determine the data volumes used by your database for the data directory.
Shutdown all Promscale Connectors.
Shutdown the original database docker image while preserving the volume mount for the data directory. You will need to mount this same directory in the new image.

Change the ownership of the data-directory to the postgres user and group in the new image. For example:

docker run -v <data_dir_volume_mount>:/var/lib/postgresql/data timescale/timescaledb-ha:pg14-latest chown -R postgres:postgres /var/lib/postgresql/data

Start the new docker container with the same volume mounts as what the original container used.
Connect to the new database using psql and reindex all the data that has data that is collatable. This is necessary because the collation in the Alpine image is broken and so BTREE-based indexes will be incorrect until they are reindexed. It is extremely important to execute this step before ingesting new data to avoid data corruption. Note: This process can take a long time depending on how much indexed textual data the database has. You should use the following query to reindex all the necessary indexes:
```
DO $$DECLARE r record;
  BEGIN
    FOR r IN
      SELECT DISTINCT indclass
          FROM (SELECT indexrelid::regclass indclass, unnest(string_to_array(indcollation::text, ' ')) coll FROM pg_catalog.pg_index) sub
          INNER JOIN pg_catalog.pg_class c ON (c.oid = sub.indclass)
          WHERE coll !='0' AND c.relkind != 'I'
    LOOP
     EXECUTE 'REINDEX INDEX ' || r.indclass;
  END LOOP;
END$$;
```
Restart the Promscale Connector

If you are using Kubernetes instead of plain docker you should:

Shutdown the Promscale Connector pods
Change the database pod to use the debian docker image and restart it.
Execute jobs for the script in steps 4 and 6 above.
Restart the Promscale Connector pods.

Found an issue on this page?

Report an issue!

Keywords

Promscale analytics Docker

PreviousInstall Promscale on Kubernetes NextInstall Promscale from source

Install Promscale using a pre-built Docker container

Install Promscale with Docker

Installing Promscale using Docker run

Upgrading from the previous alpine image

Related Content