diff --git a/_partials/_install-self-hosted-docker-based.mdx b/_partials/_install-self-hosted-docker-based.mdx index 2740b4724f..83103bbae7 100644 --- a/_partials/_install-self-hosted-docker-based.mdx +++ b/_partials/_install-self-hosted-docker-based.mdx @@ -1,62 +1,214 @@ + + + + -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 `` 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 :/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. + + + +## 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 :/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]. + + + + + + + +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]. + + + + [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/ diff --git a/self-hosted/install/installation-docker.md b/self-hosted/install/installation-docker.md index 18b70b9294..6e2143e032 100644 --- a/self-hosted/install/installation-docker.md +++ b/self-hosted/install/installation-docker.md @@ -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 @@ -37,97 +37,12 @@ $TIMESCALE_DB on a [supported platform](#supported-platforms) using containers s -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. - - - -The two container types store $PG data dir in different places, -make sure you select the correct one to mount: - - -|Container|PGDATA location| -|-|-| -`timescaledb-ha`|`/home/postgres/pgdata/data` -`timescaledb`| `/var/lib/postgresql/data` - - - - -```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 -[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/ + diff --git a/self-hosted/upgrades/upgrade-docker.md b/self-hosted/upgrades/upgrade-docker.md index 0a99265c2f..65aa6af09c 100644 --- a/self-hosted/upgrades/upgrade-docker.md +++ b/self-hosted/upgrades/upgrade-docker.md @@ -1,5 +1,5 @@ --- -title: Upgrade within a Docker container +title: Upgrade TimescaleDB running in Docker excerpt: Upgrade self-hosted TimescaleDB running in a Docker container to a new minor version products: [self_hosted] keywords: [upgrades, Docker] @@ -7,17 +7,17 @@ keywords: [upgrades, Docker] import ConsiderCloud from "versionContent/_partials/_consider-cloud.mdx"; -# Upgrade TimescaleDB running in Docker +# Upgrade $TIMESCALE_DB running in Docker -If you originally installed TimescaleDB using Docker, you can upgrade from within the Docker -container. This allows you to upgrade to the latest TimescaleDB version while retaining your data. +If you originally installed $TIMESCALE_DB using Docker, you can upgrade from within the Docker +container. This allows you to upgrade to the latest $TIMESCALE_DB version while retaining your data. The `timescale/timescaledb-ha*` images have the files necessary to run previous versions. Patch releases only contain bugfixes so should always be safe. Non-patch releases may rarely require some extra steps. -These steps are mentioned in the [release notes][relnotes] for the version of TimescaleDB +These steps are mentioned in the [release notes][relnotes] for the version of $TIMESCALE_DB that you are upgrading to. -After you upgrade the docker image, you run `ALTER EXTENSION` for all databases using TimescaleDB. +After you upgrade the docker image, you run `ALTER EXTENSION` for all databases using $TIMESCALE_DB. @@ -35,34 +35,39 @@ mounts, or bind mounts. -### Determining the mount point type - -1. Work out what type of mount your Docker container uses by running this - command, which returns either `volume` or `bind`: +1. Find the mount type used by your Docker container: ```bash docker inspect timescaledb --format='{{range .Mounts }}{{.Type}}{{end}}' ``` + This returns either `volume` or `bind`. -1. Get the current name or mount path with this command, and record it to use - when you perform the upgrade. Make sure you copy the correct command, based - on your mount point type. +1. Note the volume or bind used by your container: - + ```bash docker inspect timescaledb --format='{{range .Mounts }}{{.Name}}{{end}}' + ``` + Docker returns the ``. You see something like this: + + ``` 069ba64815f0c26783b81a5f0ca813227fde8491f429cf77ed9a5ae3536c0b2c ``` - + ```bash docker inspect timescaledb --format='{{range .Mounts }}{{.Source}}{{end}}' + ``` + + Docker returns the ``. You see something like this: + + ``` /path/to/data ``` @@ -70,47 +75,50 @@ mounts, or bind mounts. + You use this value when you perform the upgrade. + -## Upgrade TimescaleDB within Docker +## Upgrade $TIMESCALE_DB within Docker -To upgrade TimescaleDB within Docker, you need to download the upgraded image, +To upgrade $TIMESCALE_DB within Docker, you need to download the upgraded image, stop the old container, and launch the new container pointing to your existing data. + + + + -### Upgrading TimescaleDB within Docker +1. **Pull the latest $TIMESCALE_DB image** -1. Pull the latest TimescaleDB image. This command pulls the image for - TimescaleDB 2.17.x running on $PG 17. If you're using another $PG version, - look for the relevant tag in the - [TimescaleDB HA Docker Hub repository](https://hub.docker.com/r/timescale/timescaledb-ha/tags). + This command pulls the latest version of $TIMESCALE_DB running on $PG 17: - ```bash + ``` docker pull timescale/timescaledb-ha:pg17 ``` -1. Stop the old container, and remove it: + If you're using another version of $PG, look for the relevant tag in the [$TIMESCALE_DB HA](https://hub.docker.com/r/timescale/timescaledb-ha/tags) repository on Docker Hub. + +1. **Stop the old container, and remove it** ```bash docker stop timescaledb docker rm timescaledb ``` -1. Launch a new container with the upgraded Docker image, pointing to the - existing mount point. Make sure you copy the correct command, based on your - mount point type. +1. **Launch a new container with the upgraded Docker image** - For volume mounts: + Launch based on your mount point type: - + ```bash - docker run -v 069ba64815f0c26783b81a5f0ca813227fde8491f429cf77ed9a5ae3536c0b2c:/var/lib/postgresql/data \ - -d --name timescaledb -p 5432:5432 timescale/timescaledb-ha + docker run -v :/home/postgres/pgdata/data + -d --name timescaledb -p 5432:5432 timescale/timescaledb-ha:pg17 ``` @@ -118,40 +126,113 @@ data. ```bash - docker run -v /path/to/data:/var/lib/postgresql/data -d --name timescaledb \ - -p 5432:5432 timescale/timescaledb-ha + docker run -v :/home/postgres/pgdata/data -d --name timescaledb \ + -p 5432:5432 timescale/timescaledb-ha:pg17 ``` -1. Connect to the upgraded instance using `psql` with the `-X` flag: +1. **Connect to the upgraded instance using `psql` with the `-X` flag** ```bash docker exec -it timescaledb psql -U postgres -X ``` -1. At the psql prompt, use the `ALTER` command to upgrade the extension: +1. **At the psql prompt, use the `ALTER` command to upgrade the extension** - ```sql + ``` ALTER EXTENSION timescaledb UPDATE; + CREATE EXTENSION IF NOT EXISTS timescaledb_toolkit; + ALTER EXTENSION timescaledb_toolkit UPDATE; + ``` + +The [$TOOLKIT_LONG][toolkit] extension is packaged with $TIMESCALE_DB HA, it includes additional +hyperfunctions to help you with queries and data analysis. + + + +If you have multiple databases, update each database separately. + + + + + + + + + + + + +1. **Pull the latest $TIMESCALE_DB image** + + This command pulls the latest version of $TIMESCALE_DB running on $PG 17. + + ``` + docker pull timescale/timescaledb:latest-pg17 ``` -1. Update the [$TOOLKIT_LONG][toolkit] extension. $TOOLKIT_SHORT is packaged - with TimescaleDB's HA Docker image, and includes additional hyperfunctions - to help you with queries and data analysis: + If you're using another version of $PG, look for the relevant tag in the [TimescaleDB light](https://hub.docker.com/r/timescale/timescaledb) repository on Docker Hub. + +1. **Stop the old container, and remove it** + + ```bash + docker stop timescaledb + docker rm timescaledb + ``` + +1. **Launch a new container with the upgraded Docker image** + + Launch based on your mount point type: + + + + + + ```bash + docker run -v :/var/lib/postgresql/data \ + -d --name timescaledb -p 5432:5432 timescale/timescaledb:latest-pg17 + ``` + + + + + + ```bash + docker run -v : -d --name timescaledb \ + -p 5432:5432 timescale/timescaledb:latest-pg17 + ``` + + + + + +1. **Connect to the upgraded instance using `psql` with the `-X` flag** + + ```bash + docker exec -it timescaledb psql -U postgres -X + ``` + +1. **At the psql prompt, use the `ALTER` command to upgrade the extension** ```sql - CREATE EXTENSION IF NOT EXISTS timescaledb_toolkit; - ALTER EXTENSION timescaledb_toolkit UPDATE; + ALTER EXTENSION timescaledb UPDATE; ``` + If you have multiple databases, you need to update each database separately. + + + + + + [toolkit]: /self-hosted/:currentVersion:/tooling/install-toolkit/ [relnotes]: https://github.com/timescale/timescaledb/releases