Skip to content

Update docker install and updater #4246

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 17 commits into from
Jul 7, 2025
Merged

Update docker install and updater #4246

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
cabf67a
chore: first go.
billy-the-fish Jun 30, 2025
db032b5
tabs
atovpeko Jul 1, 2025
9a80482
Merge branch 'latest' of github.com:timescale/docs into 4203-feedback…
atovpeko Jul 2, 2025
9bce8ea
review
atovpeko Jul 2, 2025
9b943fa
Merge branch 'latest' into 4203-feedback-page-self-hostedlatestupgrad…
atovpeko Jul 3, 2025
6e3772f
Update self-hosted/upgrades/upgrade-docker.md
atovpeko Jul 3, 2025
a46c350
Update self-hosted/upgrades/upgrade-docker.md
atovpeko Jul 3, 2025
8242bf0
Update self-hosted/upgrades/upgrade-docker.md
atovpeko Jul 3, 2025
15cd39e
Update self-hosted/upgrades/upgrade-docker.md
atovpeko Jul 3, 2025
fcf105f
Update self-hosted/upgrades/upgrade-docker.md
atovpeko Jul 3, 2025
da9539b
updates on review
atovpeko Jul 3, 2025
fd3a2ba
Merge branch 'latest' into 4203-feedback-page-self-hostedlatestupgrad…
billy-the-fish Jul 4, 2025
8b9be28
chore: change to force build update.
billy-the-fish Jul 4, 2025
0db48fa
chore: force volume in the HA image.
billy-the-fish Jul 4, 2025
b60adc2
chore: and clean up.
billy-the-fish Jul 4, 2025
061ee42
Merge branch 'latest' into 4203-feedback-page-self-hostedlatestupgrad…
billy-the-fish Jul 4, 2025
d0cacdc
Merge branch 'latest' into 4203-feedback-page-self-hostedlatestupgrad…
billy-the-fish Jul 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
198 changes: 175 additions & 23 deletions _partials/_install-self-hosted-docker-based.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,62 +1,214 @@
<Tabs label="Install TimescaleDB with Docker">

<Tab title="TimescaleDB-HA">

<Procedure>
In Terminal:

1. **Run the $TIMESCALE_DB Docker image**

The [TimescaleDB HA](https://hub.docker.com/r/timescale/timescaledb-ha) Docker image offers the most complete $TIMESCALE_DB experience. It uses [Ubuntu][ubuntu], includes [$TOOLKIT_LONG](https://github.com/timescale/timescaledb-toolkit), and support for PostGIS and Patroni. The latest release based on $PG 17 is `timescale/timescaledb-ha:pg17`:
The [$TIMESCALE_DB HA](https://hub.docker.com/r/timescale/timescaledb-ha) Docker image offers the most complete
$TIMESCALE_DB experience. It uses [Ubuntu][ubuntu], includes
[$TOOLKIT_LONG](https://github.com/timescale/timescaledb-toolkit), and support for PostGIS and Patroni.

```bash
To install the latest release based on $PG 17:

```
docker pull timescale/timescaledb-ha:pg17
```

The lighter-weight [TimescaleDB](https://hub.docker.com/r/timescale/timescaledb) non-ha Docker image uses [Alpine][alpine]. The latest release based on $PG 17 is `timescale/timescaledb:latest-pg17`.
$TIMESCALE_DB is pre-created in the default $PG database and is added by default to any new database you create in this image.

1. **Run the container**

Replace `</a/local/data/folder>` with the path to the folder you want to keep your data in the following command.
```
docker run -d --name timescaledb -p 5432:5432 -v </a/local/data/folder>:/pgdata -e PGDATA=/pgdata -e POSTGRES_PASSWORD=password timescale/timescaledb-ha:pg17
```

If you are running multiple container instances, change the port each Docker instance runs on.

On UNIX-based systems, Docker modifies Linux IP tables to bind the container. If your system uses Linux Uncomplicated Firewall (UFW), Docker may
[override your UFW port binding settings][override-binding]. To prevent this, add `DOCKER_OPTS="--iptables=false"` to `/etc/default/docker`.

$TIMESCALE_DB is pre-created in the default $PG database in both the -ha and non-ha Docker images.
By default, $TIMESCALE_DB is added to any new database you create in these images.
1. **Connect to a database on your $PG instance**

1. **Run the container**
The default user and database are both `postgres`. You set the password in `POSTGRES_PASSWORD` in the previous step. The default command to connect to $PG is:

```bash
docker run -d --name timescaledb -p 5432:5432 -e POSTGRES_PASSWORD=password timescale/timescaledb-ha:pg17
psql -d "postgres://postgres:password@localhost/postgres"
```

If you are running multiple container instances remember to change the port each Docker instance runs on.
1. **Check that $TIMESCALE_DB is installed**

```sql
\dx
```

You see the list of installed extensions:

On UNIX based systems, Docker modifies Linux IP tables to bind the container. If your system uses
Linux Uncomplicated Firewall (UFW), Docker may
[override your UFW port binding settings](https://www.techrepublic.com/article/how-to-fix-the-docker-and-ufw-security-flaw/).
To prevent this, add `DOCKER_OPTS="--iptables=false"` to `/etc/default/docker`.
```sql
Name | Version | Schema | Description
---------------------+---------+------------+---------------------------------------------------------------------------------------
plpgsql | 1.0 | pg_catalog | PL/pgSQL procedural language
timescaledb | 2.20.3 | public | Enables scalable inserts and complex queries for time-series data (Community Edition)
timescaledb_toolkit | 1.21.0 | public | Library of analytical hyperfunctions, time-series pipelining, and other SQL utilities
(3 rows)
```

1. **Connect to a database on your $PG instance**
Press `q` to exit the list of extensions.

</Procedure>

## More Docker options

If you want to access the container from the host but avoid exposing it to the
outside world, you can bind to `127.0.0.1` instead of the public interface, using this command:

```bash
docker run -d --name timescaledb -p 127.0.0.1:5432:5432 \
-v </a/local/data/folder>:/pgdata -e PGDATA=/pgdata -e POSTGRES_PASSWORD=password timescale/timescaledb-ha:pg17
```

If you don't want to install `psql` and other $PG client tools locally,
or if you are using a Microsoft Windows host system, you can connect using the
version of `psql` that is bundled within the container with this command:

```bash
docker exec -it timescaledb psql -U postgres
```

When you install $TIMESCALE_DB using a Docker container, the $PG settings
are inherited from the container. In most cases, you do not need to adjust them.
However, if you need to change a setting, you can add `-c setting=value` to your
Docker `run` command. For more information, see the
[Docker documentation][docker-postgres].

The link provided in these instructions is for the latest version of $TIMESCALE_DB
on $PG 17. To find other Docker tags you can use, see the [Dockerhub repository][dockerhub].

## View logs in Docker

If you have $TIMESCALE_DB installed in a Docker container, you can view your logs
using Docker, instead of looking in `/var/lib/logs` or `/var/logs`. For more
information, see the [Docker documentation on logs][docker-logs].

</Tab>

<Tab title="TimescaleDB light">

<Procedure>

1. **Run the $TIMESCALE_DB Docker image**

The light-weight [$TIMESCALE_DB](https://hub.docker.com/r/timescale/timescaledb) Docker image uses [Alpine][alpine] and does not contain [$TOOLKIT_LONG](https://github.com/timescale/timescaledb-toolkit) or support for PostGIS and Patroni.

To install the latest release based on $PG 17:

```
docker pull timescale/timescaledb:latest-pg17
```

$TIMESCALE_DB is pre-created in the default $PG database and added by default to any new database you create in this image.


1. **Run the container**

```
docker run -d --name timescaledb -p 5432:5432 -e POSTGRES_PASSWORD=password timescale/timescaledb:latest-pg17
```

If you are running multiple container instances, change the port each Docker instance runs on.

On UNIX-based systems, Docker modifies Linux IP tables to bind the container. If your system uses Linux Uncomplicated Firewall (UFW), Docker may [override your UFW port binding settings][override-binding]. To prevent this, add `DOCKER_OPTS="--iptables=false"` to `/etc/default/docker`.

1. **Connect to a database on your $PG instance**

The default user and database are both `postgres`. You set the password in `POSTGRES_PASSWORD` in the previous step. The default command to connect to $PG in this image is:

```bash
psql -d "postgres://postgres:password@localhost/postgres"
```

The default user and database are both `postgres`. You set the password in
`POSTGRES_PASSWORD` in the previous step. The default command to connect to $PG in this image is:

1. **Check that $TIMESCALE_DB is installed**

```sql
\dx
```

You see the list of installed extensions:
You see the list of installed extensions:

```sql
List of installed extensions
Name | Version | Schema | Description
---------------------+---------+------------+---------------------------------------------------------------------------------------
plpgsql | 1.0 | pg_catalog | PL/pgSQL procedural language
timescaledb | 2.17.2 | public | Enables scalable inserts and complex queries for time-series data (Community Edition)
timescaledb_toolkit | 1.19.0 | public | Library of analytical hyperfunctions, time-series pipelining, and other SQL utilities
(3 rows)
timescaledb | 2.20.3 | public | Enables scalable inserts and complex queries for time-series data (Community Edition)
```
Press q to exit the list of extensions.

Press `q` to exit the list of extensions.

## More Docker options

If you want to access the container from the host but avoid exposing it to the
outside world, you can bind to `127.0.0.1` instead of the public interface, using this command:

```bash
docker run -d --name timescaledb -p 127.0.0.1:5432:5432 \
-e POSTGRES_PASSWORD=password timescale/timescaledb:latest-pg17
```

If you don't want to install `psql` and other $PG client tools locally,
or if you are using a Microsoft Windows host system, you can connect using the
version of `psql` that is bundled within the container with this command:

```bash
docker exec -it timescaledb psql -U postgres
```

Existing containers can be stopped using `docker stop` and started again with
`docker start` while retaining their volumes and data. When you create a new
container using the `docker run` command, by default you also create a new data
volume. When you remove a Docker container with `docker rm`, the data volume
persists on disk until you explicitly delete it. You can use the `docker volume
ls` command to list existing docker volumes. If you want to store the data from
your Docker container in a host directory, or you want to run the Docker image
on top of an existing data directory, you can specify the directory to mount a
data volume using the `-v` flag:

```bash
docker run -d --name timescaledb -p 5432:5432 \
-v /your/data/dir:/home/postgres/pgdata/data \
-e POSTGRES_PASSWORD=password timescale/timescaledb:latest-pg17
```

When you install $TIMESCALE_DB using a Docker container, the $PG settings
are inherited from the container. In most cases, you do not need to adjust them.
However, if you need to change a setting, you can add `-c setting=value` to your
Docker `run` command. For more information, see the
[Docker documentation][docker-postgres].

The link provided in these instructions is for the latest version of $TIMESCALE_DB
on $PG 16. To find other Docker tags you can use, see the [Dockerhub repository][dockerhub].

## View logs in Docker

If you have $TIMESCALE_DB installed in a Docker container, you can view your logs
using Docker, instead of looking in `/var/lib/logs` or `/var/logs`. For more
information, see the [Docker documentation on logs][docker-logs].

</Procedure>

</Tab>

</Tabs>

[config]: /self-hosted/:currentVersion:/configuration/
[alpine]: https://alpinelinux.org/
[ubuntu]: https://ubuntu.com
[override-binding]: https://www.techrepublic.com/article/how-to-fix-the-docker-and-ufw-security-flaw/
[alpine]: https://alpinelinux.org/
[config]: /self-hosted/:currentVersion:/configuration/
[docker-postgres]: https://hub.docker.com/_/postgres
[dockerhub]: https://hub.docker.com/r/timescale/timescaledb/tags?page=1&ordering=last_updated
[ubuntu]: https://ubuntu.com
[docker-logs]: https://docs.docker.com/engine/logging/
[install-from-source]: /self-hosted/:currentVersion:/install/installation-source/
93 changes: 4 additions & 89 deletions self-hosted/install/installation-docker.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,8 @@ import AddTimescaleDBToDB from "versionContent/_partials/_add-timescaledb-to-a-d

# Install $TIMESCALE_DB from a Docker container

TimescaleDB is a [$PG extension](https://www.postgresql.org/docs/current/external-extensions.html) for
time series and demanding workloads that ingest and query high volumes of data. You can install a TimescaleDB
$TIMESCALE_DB is a [$PG extension](https://www.postgresql.org/docs/current/external-extensions.html) for
time series and demanding workloads that ingest and query high volumes of data. You can install a $TIMESCALE_DB
instance on any local system from a pre-built Docker container.

This section shows you how to
Expand All @@ -37,97 +37,12 @@ $TIMESCALE_DB on a [supported platform](#supported-platforms) using containers s
<SelfHostedDocker />


And that is it! You have TimescaleDB running on a database on a self-hosted instance of $PG.

## More Docker options

If you want to run the image directly from the container, you can use this
command:

```bash
docker run -d --name timescaledb -p 5432:5432 -e POSTGRES_PASSWORD=password timescale/timescaledb-ha:pg17
```

The `-p` flag binds the container port to the host port. This means that
anything that can access the host port can also access your TimescaleDB container,
so it's important that you set a $PG password using the
`POSTGRES_PASSWORD` environment variable. Without that variable, the Docker
container disables password checks for all database users.

If you want to access the container from the host but avoid exposing it to the
outside world, you can bind to `127.0.0.1` instead of the public interface,
using this command:

```bash
docker run -d --name timescaledb -p 127.0.0.1:5432:5432 \
-e POSTGRES_PASSWORD=password timescale/timescaledb-ha:pg17
```

If you don't want to install `psql` and other $PG client tools locally,
or if you are using a Microsoft Windows host system, you can connect using the
version of `psql` that is bundled within the container with this command:

```bash
docker exec -it timescaledb psql -U postgres
```

Existing containers can be stopped using `docker stop` and started again with
`docker start` while retaining their volumes and data. When you create a new
container using the `docker run` command, by default you also create a new data
volume. When you remove a Docker container with `docker rm` the data volume
persists on disk until you explicitly delete it. You can use the `docker volume
ls` command to list existing docker volumes. If you want to store the data from
your Docker container in a host directory, or you want to run the Docker image
on top of an existing data directory, you can specify the directory to mount a
data volume using the `-v` flag.

<Highlight type="warning">

The two container types store $PG data dir in different places,
make sure you select the correct one to mount:

<!-- vale Vale.Terms = NO -->
|Container|PGDATA location|
|-|-|
`timescaledb-ha`|`/home/postgres/pgdata/data`
`timescaledb`| `/var/lib/postgresql/data`
<!-- vale Vale.Terms = YES -->

</Highlight>

```bash
docker run -d --name timescaledb -p 5432:5432 \
-v /your/data/dir:/home/postgres/pgdata/data \
-e POSTGRES_PASSWORD=password timescale/timescaledb-ha:pg17
```

When you install TimescaleDB using a Docker container, the $PG settings
are inherited from the container. In most cases, you do not need to adjust them.
However, if you need to change a setting you can add `-c setting=value` to your
Docker `run` command. For more information, see the
[Docker documentation][docker-postgres].

The link provided in these instructions is for the latest version of TimescaleDB
on $PG 16. To find other Docker tags you can use, see the
[Dockerhub repository][dockerhub].


### View logs in Docker

If you have TimescaleDB installed in a Docker container, you can view your logs
using Docker, instead of looking in `/var/lib/logs` or `/var/logs`. For more
information, see the [Docker documentation on logs][docker-logs].
And that is it! You have $TIMESCALE_DB running on a database on a self-hosted instance of $PG.

## Where to next

<WhereTo />

[alpine]: https://alpinelinux.org/
[config]: /self-hosted/:currentVersion:/configuration/
[docker-install]: https://docs.docker.com/get-started/get-docker/
[docker-postgres]: https://hub.docker.com/_/postgres
[dockerhub]: https://hub.docker.com/r/timescale/timescaledb/tags?page=1&ordering=last_updated
[install-psql]: https://www.timescale.com/blog/how-to-install-psql-on-mac-ubuntu-debian-windows/
[ubuntu]: https://ubuntu.com
[docker-logs]: https://docs.docker.com/engine/logging/
[install-from-source]: /self-hosted/:currentVersion:/install/installation-source/

Loading