Log inSign upBook a demo
Tines Stories
  1. Docs
  2. Self-Hosted
  3. Upgrading Tines
  1. Docs
  2. Self-Hosted
  3. Upgrading Tines

Infrastructure Maintenance

Last updated

This guide is designed to help you upgrade your self-hosted Tines Stories infrastructure and its external components. Before attempting any operations in this guide, we strongly urge you to take backups of your database. We also suggest that you do not upgrade Tines versions while making core infrastructure changes.

Shutdown and Startup of Tines Stories Services

If you are performing maintenance or migrations on the underlying infrastructure hosting Tines Stories, follow the preferred order below to gracefully shut down. Following these steps will cause downtime for your Tines tenant. This order is applicable to Docker Compose, ECS, and Kubernetes. For each step, reduce the number of running instances to zero.

Before starting the shutdown process, review the section "Checking tines-sidekiq queue size." If samples show non-zero values that are not reducing, you should scale the tines-sidekiq service before starting the shutdown.

Scale-down order:

  1. nginx or other proxy service (if applicable)

  2. tines-app

  3. tines-sidekiq (Ensure the queue size reaches near 0 and is not increasing during sampling before proceeding).

  4. tines-command-runner

  5. Redis/Valkey

  6. Postgres

  7. pypi-server

Examples of scaling down by platform:

Docker Compose:

docker compose stop tines-app

ECS:

aws ecs update-service --cluster tines --service tines-app --desired-count 0

Kubernetes:

kubectl scale deployment tines-app --replicas=0

Checking tines-sidekiq Queue Size

Run the following Rails command from within a tines-sidekiq container to check the queue size. Run this command multiple times over a 2–5 minute window to ensure the volume is decreasing.

bundle exec rails runner "puts JSON.pretty_generate(Sidekiq::Queue.all.map { |q| { name: q.name, size: q.size, latency: q.latency.round(2), paused: q.paused? } })"

Accessing the container:

aws ecs execute-command --cluster \
--task \
--container tines-sidekiq \
--interactive \
--command "/bin/bash

Migrating to a New Database Instance

Before performing operations on your PostgreSQL instance, ensure you have recent backups and snapshots in place. Migration time varies based on data volume and network speed. Do not run this process from a laptop or any machine that may enter sleep mode.

Prerequisites:

  1. All Tines Stories services shut down except Postgres.

  2. A host with pg_dump and pg_restore installed.

  3. Network connectivity between source and destination databases.

  4. Adequate local storage for the dump file.

  5. Existing DATABASE_NAME and DATABASE_HOST configuration details.

Export

pg_dump -h <existing_db_host> \
        -U <username> \
        -d <database_name> \
        -Fc \
        -v \
        -f tines_migration_snapshot.dump

Import

pg_restore -h <new_db_host> \
           -U <username> \
           -d <database_name> \
           -v \
           tines_migration_snapshot.dump

Migrating to a New Redis/Valkey Instance

Redis/Valkey is an in-memory, transient datastore that does not require manual migrations or backups.

Valkey is a compatible replacement for Redis. Shut Tines down before you change the image, using the order in Shutdown and startup of Tines services. This causes downtime. Make this change on its own, separate from a Tines version upgrade. Keep the existing data volume. Valkey 7.2 continues from the data Redis has already written, including queued work and signed-in sessions.


Docker Compose

In the environment file for your Compose project, set:

TINES_REDIS_IMAGE=oci.tines.com/tines/valkey:7.2.14

The Compose file uses that variable for the Redis service. Keep the start command, service name, port, and data volume as they are. Leave REDIS_URL as it is. If Redis already has a password, keep that configuration. If the image is set directly on the redis service in docker-compose.yml, change it to 

oci.tines.com/tines/valkey:7.2.14

Start Redis, then start the rest of Tines:

docker compose up -d redis
docker compose up -d


Helm

From Helm chart 43.4.0, the bundled Redis container is Valkey 7.2. Upgrade the chart with your existing values file. You can leave REDIS_URL as is. If you are on an older chart and you run the bundled container, set the image in your values file, then upgrade:

deployments:
  redis:
    image:
      registry: oci.tines.com
      repository: tines/valkey
      tag: 7.2.14

On OpenShift, upgrade to chart 43.4.0 or later. The chart selects the OpenShift Valkey image for you.


Hosted Redis

If Redis is a hosted service, create a Valkey endpoint with your provider. Take a snapshot after Tines has shut down and restore it onto the Valkey endpoint before you start Tines again. Taking it after shutdown means the snapshot includes the work that Sidekiq put back on the queue as it stopped. Most providers do this with a backup and restore, or by seeding the new instance from an RDB file. Point Tines at the new Valkey endpoint with the steps in Changing DNS for external services.

If you skip the snapshot, Tines starts with an empty queue and everyone has to sign in again. Stories, cases, and other product data are not affected.

Changing DNS for External Services

Changing the DNS for external services (e.g., Redis/Valkey or Postgres) should never be performed while Tines Stories is running.

Update the following values in your configuration:

Docker Compose and ECS (.env):

REDIS_URL=redis://<new_dns_host>:6379/1
DATABASE_HOST=<new_dns_host>

Helm (values.yaml):

tinesApp:
  databaseConfiguration:
    DATABASE_HOST: <new_dns_host>
  redisConfiguration:
    REDIS_URL: redis://<new_dns_host>:6379/1

Note: Before restarting Tines Stories, ensure the new DNS entry has propagated and is accessible from your infrastructure. At a minimum, wait for the duration of the DNS TTL and flush any local DNS caches if necessary.

Was this helpful?