Skip to content
Klutch.sh Docs

Deploying a Tracardi App

Introduction

Tracardi is an open-source customer data and journey automation platform built on FastAPI. This guide covers building a Docker image, wiring it to Elasticsearch (and optional Redis), securing admin access, and deploying to Klutch.sh over HTTP.

Prerequisites

  • GitHub repository containing your Dockerfile.
  • Managed Elasticsearch/OpenSearch endpoint (or a separately deployed cluster).
  • Optional Redis instance for queues and caching.
  • Klutch.sh project ready in klutch.sh/app.

Project structure

.
└── Dockerfile

Sample Dockerfile

FROM tracardi/tracardi-api:latest


# Default Tracardi port
ENV TRACARDI_HOST=0.0.0.0 \
    TRACARDI_PORT=8686


EXPOSE 8686
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8686"]

Required environment variables

  • ELASTIC_HOST – Elasticsearch host (no protocol).
  • ELASTIC_PORT – e.g., 9200.
  • ELASTIC_SCHEME – http or https.
  • ELASTIC_USER and ELASTIC_PASSWORD – if security is enabled.
  • ADMIN_USER and ADMIN_PASSWORD – credentials for the admin UI.
  • SECRET_KEY – secure random string for JWT/session signing.

Optional environment variables

  • REDIS_HOST / REDIS_PORT / REDIS_PASSWORD – if using Redis for queues/caching.
  • TRACARDI_PORT – override if you change the internal port.
  • TRACARDI_DEBUG=false – keep debug disabled in production.

Persistence

Tracardi stores data in Elasticsearch. If you log locally, attach a volume for logs/backups:

  • Mount path: /var/log/tracardi
  • Size: based on expected retention

Networking

  • Protocol: HTTP
  • Internal port: 8686
  • Users reach https://example-app.klutch.sh while Klutch.sh routes to port 8686 in the container.
Terminal window
curl -I http://localhost:8686/health

Deployment on Klutch.sh

  1. Push your Dockerfile to GitHub.
  2. In klutch.sh/app, create a new app and select GitHub as the source.
  3. Klutch.sh automatically detects the Dockerfile in the repository root.
  4. Select HTTP traffic and set the internal port to 8686.
  5. Configure environment variables for Elasticsearch (ELASTIC_HOST, ELASTIC_PORT, ELASTIC_SCHEME, credentials), admin access (ADMIN_USER, ADMIN_PASSWORD), and SECRET_KEY. Add Redis vars if used.
  6. Optionally attach a persistent volume at /var/log/tracardi for log retention.
  7. Deploy. After first boot, sign in with the admin user to complete setup.

Verification

  • UI: open https://example-app.klutch.sh and confirm the dashboard loads.

  • API health:

    Terminal window
    curl -s https://example-app.klutch.sh/health

Next steps

  • Set up TLS and user roles in Elasticsearch.
  • Enable backups for your Elasticsearch cluster.
  • Tune worker and queue settings if using Redis for high-throughput ingestion.