---
# System prepended metadata

title: Running TimescaleDB with Docker
tags: [docker, timescaledb]

---

# Running TimescaleDB with Docker

This document describes how to run **TimescaleDB** as a Docker container using
a simple and production-friendly setup.

The goal is to run PostgreSQL + TimescaleDB in a containerized environment
with persistent storage, while keeping the database accessible only to
internal services.

The full script is provided at the end.

---

## What are we trying to achieve?

With this setup, we want to:

- Run TimescaleDB as a Docker container
- Use a pinned image version for reproducibility
- Persist database data across restarts
- Avoid exposing database ports publicly
- Keep database access limited to internal services

This approach works well for backend APIs, analytics workloads,
and time-series use cases.

---

## General approach

In this setup:

- The official `timescale/timescaledb` Docker image is used
- Database credentials are provided via environment variables
- Data is persisted using a named Docker volume
- The container is attached to an **internal Docker network**

> In this example, the network is called `app-net`.  
> This is a personal preference and can be replaced with any Docker network
> that fits your architecture.

This keeps the setup **simple**, **secure**, and easy to maintain.

---

## Prerequisites

Before running the script:

- Docker is installed
- A Docker network already exists for internal communication
- You are familiar with managing secrets outside the script (recommended)

> Example network creation:
> `docker network create app-net`

---

## Step 1: Running Bash in safe mode

The script starts with strict Bash options enabled:

- Exit immediately on errors
- Fail on undefined variables
- Catch errors in pipelines

This prevents silent failures and is a best practice for infrastructure scripts.

---

## Step 2: Defining database configuration

The following parameters are defined as variables:

| Variable   | Description                     |
|------------|---------------------------------|
| `DB`       | Database name                   |
| `USER`     | Database user                   |
| `PASSWORD` | Database password               |
| `CONTAINER`| Docker container name           |
| `IMAGE`    | TimescaleDB Docker image version|

> In production, credentials should be managed via  
> `.env` files, Docker secrets, or a secrets manager.

---

## Step 3: Starting the TimescaleDB container

The container is started with:

- A persistent volume for database data
- Environment variables for initial database setup
- Attachment to the internal Docker network (`app-net`)

Internal services on the same network can connect to the database
using the container name as the hostname.

---

## Full Bash script (copy & paste)

```bash
#!/usr/bin/env bash
set -euo pipefail

# ============================================================
# TimescaleDB setup script (bash)
# ============================================================

# ------------------------------------------------------------
# Base variables
# ------------------------------------------------------------
DB="postgres"
USER="admin"
PASSWORD="PASSWORD"
CONTAINER="timescaledb"
IMAGE="timescale/timescaledb:2.24.0-pg18"

# ------------------------------------------------------------
# Start TimescaleDB container
# ------------------------------------------------------------
docker run -d \
  --name "$CONTAINER" \
  --network app-net \
  -e POSTGRES_PASSWORD="$PASSWORD" \
  -e POSTGRES_USER="$USER" \
  -e POSTGRES_DB="$DB" \
  -v timescale_data:/var/lib/postgresql/data \
  "$IMAGE"

echo "TimescaleDB is up 🚀 (image: $IMAGE)"