> For the complete documentation index, see [llms.txt](https://docs.pyck.cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pyck.cloud/faq/faq-operations.md).

# FAQ for System Administrators

Frequently asked questions about Pyck for system administrators

Audience: System Administrator

## Does Pyck run on-premise or in the cloud?

Pyck supports both deployment models:

* **Local development**: via Docker Compose
* **Production deployment**: via Kubernetes cluster

The standard SaaS offering runs at `https://api.pyck.ai`. On-premise deployment is fully supported through the Kubernetes/Docker architecture.

## Where is customer data stored?

Customer data is hosted on **Hetzner** servers in **Germany**.

## What happens with data when AI features are used?

Pyck uses AI to **generate code from BPMN process definitions** — not to process customer data. No live warehouse data, order data, or personal data is sent to AI providers.

Additionally, Pyck exclusively uses AI providers that offer **Zero Data Retention (ZDR)** endpoints, meaning prompts and completions are not stored or used for training by the provider. For details on the retention policy, see [OpenRouter's ZDR documentation](https://openrouter.ai/docs/guides/features/zdr#openrouters-retention-policy).

## Is there integrated user authentication?

Yes. Pyck uses **Zitadel** as its identity provider for user authentication.

## How does authentication work?

Two authentication methods are supported:

1. **JWT Token Authentication** — tokens are obtained via the Zitadel auth flow (redirect to Zitadel login page, callback with token). Tokens expire and must be renewed via the refresh token flow.
2. **Personal Access Token (PAT)** — long-lived tokens for system integrations and automation, created through the Pyck administration interface.

Both are sent as Bearer tokens in the `Authorization` header:

```
Authorization: Bearer <token>
```

For full details, see the [Authentication](/development/authentication.md) documentation.

## What environment variables are required for deployment?

All pyck binaries require the following environment variable to be set:

* **`PYCK_ENV`** (required): Specifies the environment name (e.g., `production`, `staging`, `dev`)
  * This variable **must be set explicitly** in your deployment configuration
  * The application will fail to start if this variable is missing or empty
  * Used for namespace construction (e.g., `pyck-{PYCK_ENV}-workers`)

Example configuration:

**Docker Compose:**

```yaml
environment:
  - PYCK_ENV=production
```

**Kubernetes ConfigMap:**

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: pyck-config
data:
  PYCK_ENV: "production"
```

**IMPORTANT**: As of commit `15ffdc33`, `PYCK_ENV` has no default value. Deployments that previously relied on the implicit "local" default must now explicitly set this variable.

### Optional Health Check Configuration

Temporal workers expose a `/health` HTTP endpoint (enabled by default on port 8080) to support deployment health monitoring. This endpoint verifies that the worker is actively polling Temporal task queues.

The health server can be configured via these optional environment variables:

* **`HEALTH_DISABLED`**: Set to `1` to disable the health endpoint
* **`HEALTH_PORT`**: HTTP port for health checks (default: `8080`)
* **`HEALTH_INTERVAL`**: How often to probe Temporal (default: `10s`)
* **`HEALTH_TIMEOUT`**: RPC timeout for each probe (default: `3s`)
* **`HEALTH_MAX_STALE`**: Maximum age of last successful probe before reporting unhealthy (default: `90s`)

**Example Configuration:**

```yaml
environment:
  - HEALTH_PORT=9090
  - HEALTH_INTERVAL=30s
  - HEALTH_MAX_STALE=120s
```

The health endpoint returns:

* **200 OK** when the worker is actively polling Temporal
* **503 Service Unavailable** when polling has stalled or Temporal is unreachable

This is particularly useful for container orchestrators (Kubernetes, fly.io) that need to detect and restart wedged workers.

## Why use Pyck instead of extending an existing cloud WMS?

Pyck offers a **future-proof, reliable platform with no vendor lock-in**. The open architecture, based on industry-standard technologies (Go, PostgreSQL, Kubernetes, GraphQL, Temporal), ensures you are not dependent on a single vendor's proprietary platform. You retain full control over your data, deployment model, and technology stack.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.pyck.cloud/faq/faq-operations.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.