Skip to content
This repository has been archived by the owner on Apr 2, 2024. It is now read-only.

Commit

Permalink
Fine-tune installation documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@JamesGuthrie
JamesGuthrie committed May 12, 2022
1 parent f49197a commit f3e6cdf
Show file tree
Hide file tree
Showing 2 changed files with 25 additions and 56 deletions.
66 changes: 21 additions & 45 deletions docs/binary.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,64 +2,40 @@

## 🔧 Installing pre-built binaries

You can download pre-built binaries for the Promscale
Connector [from our release page](https://github.com/timescale/promscale/releases).
A full Promscale installation consists of both the promscale connector, and a TimescaleDB instance with the Promscale
Extension installed. We provide pre-built binaries (and packages) for the both.

Download Promscale
### Setup TimescaleDB with Promscale Extension

```
curl -L -o promscale https://github.com/timescale/promscale/releases/download/<VERSION>/<PROMSCALE_DISTRIBUTION>
```

Grant executable permissions to Promscale:

```
chmod +x promscale
```
The simplest way to get started with TimescaleDB and the Promscale Extension is to install both from the TimescaleDB
package repository. You can find instructions on how to install TimescaleDB for your favourite distribution
[here](https://docs.timescale.com/install/latest/self-hosted/). Once you have installed TimescaleDB for a specific
Postgres version from our package repository, you can simply install the Promscale Extension for the same Postgres
version, e.g.:

To deploy Promscale, run the following command:

```
./promscale --db-host <DB_HOSTNAME> --db-port <DB_PORT> --db-name <DBNAME> --db-password <DB-Password> --db-ssl-mode allow
```bash
apt-get install -y promscale-extension-postgresql-14
```

Note that the flags `db-name` and `db-password` refer to the name and password of your TimescaleDB database.

Further note that the command above is to deploy Promscale with SSL mode being allowed but not required. To deploy Promscale with SSL mode enabled, configure your TimescaleDB instance with ssl certificates and drop the `--db-ssl-mode` flag. Promscale will then authenticate via SSL by default.
### Setup the Promscale Connector

We recommend installing the [promscale](https://github.com/timescale/promscale_extension/releases)
PostgreSQL extension into the TimescaleDB database you are connecting to.
Instructions on how to compile and install the extension are in the
extensions [README](https://github.com/timescale/promscale_extension/blob/master/README.md). While this isn't a requirement, it
does optimize certain queries.
Please note that the extension requires Postgres version 12 of newer.
Similarly, you can get the latest version of the Promscale Connector from the official TimescaleDB package repository.

## 🕞 Setting up cron jobs for Timescale DB 1.X

If you are using TimescaleDB 1.X you need to make sure the `execute_maintenance()`
procedure on a regular basis (e.g. via cron). We recommend executing it every
30 minutes. This is necessary to execute maintenance tasks such as enforcing
data retention policies according to the configured policy.

**Note:** This is not needed if you are using TimescaleDB 2.X because it has native support for task scheduling which
is automatically configured by Promscale to run the `execute_maintenance()` procedure.

Copy the code snippet from the file [docs/scripts/prom-execute-maintenance.sh](/docs/scripts/prom-execute-maintenance.sh) and add the database password in place of `<PASSWORD>`.
```bash
apt-get install -y promscale
```

Create an other script with the code snippet from the file [docs/scripts/install-crontab.sh](/docs/scripts/install-crontab.sh) and make sure to configure the absolute path to `prom-execute-maintenance.sh` in the script. This script will create a crontab for the above defined task.
If you're using systemd, you can use our unit and an associated configuration file to configure the Promscale connector.

Then, grant executable privileges to both files:
Otherwise, you can start the Promscale connector directly:

```
chmod +x prom-execute-maintenance.sh
chmod +x install-crontab.sh
```bash
promscale --db-host <DB_HOSTNAME> --db-port <DB_PORT> --db-name <DBNAME> --db-password <DB-Password> --db-ssl-mode allow
```

Install the cron job:
Note that the flags `db-name` and `db-password` refer to the name and password of your TimescaleDB database.

```
./install-crontab.sh
```
Further note that the command above starts the Promscale connector in "SSL allowed" mode. For production setups it's recommended to start Promscale in "SSL required" mode enabled. To do so, configure your TimescaleDB instance with ssl certificates and drop the `--db-ssl-mode` flag. Promscale will then authenticate via SSL by default.

## 🔥 Configuring Prometheus to use this remote storage connector

Expand Down
15 changes: 4 additions & 11 deletions docs/docker.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,15 +39,13 @@ If you want to run a specific version of Promscale, replace latest with the spec
**Note:** `db-ssl-mode=allow` is just for explanatory purposes. In production environments,
we advise you to use `db-ssl-mode=require` for security purposes.

This should make Promscale running along with TimescaleDB.

**Example using docker-compose:**

You can also run Promscale also by using docker-compose. The `docker-compose.yaml` is available in the
You can also run Promscale with docker-compose. The `docker-compose.yaml` is available in the
[docker-compose](https://github.com/timescale/promscale/blob/master/docker-compose/docker-compose.yaml) directory of our repository.
You can start Promscale and related services simply via `docker-compose up`.

For updating Promscale in this method, you need to stop the Promscale that is currently running using
**Note:** To update Promscale with docker-compose, you need to stop the Promscale that is currently running using
`docker-compose stop` and then pull the image with the tag you want to upgrade to with `docker pull timescale/promscale:<version-tag>`.
This will pull the respective image to your local docker registry. You can then run the updated image with `docker-compose up`.

Expand Down Expand Up @@ -94,12 +92,7 @@ You can configure Prometheus remote-write with our recommended configurations fr

The Promscale Connector binary is configured through either CLI flags, environment variables, or a YAML configuration file.

All environment variables are prefixed with `PROMSCALE`.

Configuration file is a YAML file where the keys are CLI flag names and values are their respective flag values.

The list of available cli flags is available in [here](/docs/configuration.md) in
our docs or by running with the `-h` flag (e.g. `promscale -h`).
For more information about configuration, consult our documentation [here](/docs/configuration.md).

## 🛠 Building from source

Expand All @@ -113,7 +106,7 @@ Because of [collation bugs](https://github.com/docker-library/postgres/issues/32

Our previous Alpine-based image will continue to be supported but all new installations should switch to the `timescaledb-ha` image specified above.

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

1. Use `docker inspect` to determine the data volumes used by your database for the data directory.
2. Shutdown all Promscale Connectors.
Expand Down

0 comments on commit f3e6cdf

Please sign in to comment.