Environment Variables

TaskView is configured through environment variables set in the .env.taskview file (or passed directly to the Docker container). This page documents every available variable.

Database

These must match your PostgreSQL setup.

Connection budget: the total number of Postgres connections is roughly PM2_INSTANCES × DB_POOL_MAX. Keep it below the max_connections of your PostgreSQL (default 100), leaving ~10 connections of headroom for migrations and maintenance. The API logs a warning at startup when the estimate exceeds 80.

Application

Web app

Unlike everything else on this page, this variable is set on the web app container (taskview-webapp), not in .env.taskview.

Authentication

Closing an instance: how ALLOW_PUBLIC_REGISTRATION=false works

By default anyone who can reach your instance can create an account — through the registration endpoint, or simply by entering an email on the login page (magic-link and social sign-in create the account on first login). Set ALLOW_PUBLIC_REGISTRATION=false to close the instance: from that moment accounts are created by invitation only.

Who can still get an account on a closed instance. TaskView invitations are stored by email, before any account exists. An email is considered invited — and its owner can sign in and get an account created on first login — if it appears in any of these places:

• Organization members — added via organization settings (or provisioned through SCIM)
• Project collaborators — invited to a project by an existing user

Everyone else is rejected: the registration endpoint returns 403, magic-link refuses to send a code to an unknown email, and social sign-in redirects back to the login page with an error. Existing accounts are not affected in any way — the flag only controls the creation of new ones.

SSO is not blocked by this flag. Signing in through a SAML/OIDC provider still provisions accounts, because an identity provider is configured by the administrator and is itself a controlled channel — your IdP decides who gets in.

The value must be true or false. Any other value (a typo like Flase, 0, no) stops the server at startup with a clear error instead of silently leaving the instance open.

SMTP (Email)

Required for password recovery, email confirmation, and invitation notifications. Without SMTP, these features won't work, but everything else functions normally.

Encryption

Required for SSO (SAML/OIDC) and GitHub/GitLab integrations. Secrets are encrypted at rest using AES-256-GCM.

Generate a key:

openssl rand -hex 32

What is encrypted:

• SSO: SAML certificates, SAML signing keys, OIDC client secrets
• Integrations: GitHub/GitLab OAuth tokens, webhook secrets

GitHub Integration

For connecting GitHub repositories. See GitHub, GitLab & Gitea Setup for a step-by-step guide.

GitLab Integration

For connecting GitLab repositories.

Gitea Integration

For connecting Gitea repositories.

Messaging Integrations (Telegram / Slack)

For delivering task notifications to messengers. See Telegram & Slack Setup for a step-by-step guide.

Notifications

Optional configuration for real-time and push notification delivery.

Centrifugo (real-time WebSocket notifications)

Required for in-app real-time notification delivery. Without Centrifugo, notifications are still saved to the database but will not appear instantly in the browser. Users will see them on the next page load.

Firebase Cloud Messaging (mobile push notifications)

Required for native push notifications on iOS and Android. Without Firebase, push notifications are silently skipped.

Centrifugo configuration file

Centrifugo v6 uses a nested JSON config. Create centrifugo/config.json:

{
  "client": {
    "allowed_origins": ["https://app.example.com"],
    "token": {
      "hmac_secret_key": "your_centrifugo_token_secret"
    }
  },
  "channel": {
    "namespaces": [
      {
        "name": "personal",
        "presence": false,
        "join_leave": false,
        "history_size": 0,
        "history_ttl": "0s"
      }
    ]
  },
  "http_api": {
    "key": "your_centrifugo_api_key"
  }
}

• http_api.key must match CENTRIFUGO_API_KEY in .env.taskview
• client.token.hmac_secret_key must match CENTRIFUGO_TOKEN_SECRET in .env.taskview
• client.allowed_origins should list your frontend domain(s). Use ["*"] only for development.

Nginx WebSocket proxy

To serve Centrifugo through your existing HTTPS domain, add to your nginx server block:

location /centrifugo/ {
    proxy_pass http://localhost:8000/;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

Then set CENTRIFUGO_PUBLIC_URL=wss://api.example.com/centrifugo/connection/websocket.

Files (task attachments)

Uploaded files are stored outside PostgreSQL; the database keeps only metadata (name, size, SHA-256 checksum, which provider holds the bytes). Two providers are supported and both may be configured at the same time, which is how an instance is migrated from one to the other without downtime.

Attachments are off until a provider is configured: FILE_STORAGE_PROVIDER must name a provider and all of that provider's variables must be set. Otherwise the API starts normally, logs a warning with what is missing, hides the upload buttons in the web app and answers uploads with 503. There is no default directory on purpose: in Docker an unmounted directory lives inside the container and is lost when the container is recreated.

Storage quotas

Quotas limit how much each organization can store. They are on by default: every organization gets 100 MB unless configured otherwise.

Each organization, personal ones included, has its own quota: FILE_QUOTA_ORGANIZATION_MB by default, or the value of tv_auth.organizations.file_quota_mb (in megabytes) when it is set. The API never changes this column; set it from billing or by hand:

UPDATE tv_auth.organizations SET file_quota_mb = 20480 WHERE id = <organization id>;

Usage is a live sum of the files in the organization's projects, so deleting a file frees its space at once. Lowering a quota below current usage only blocks new uploads; nothing is deleted. The quota is never exceeded, parallel uploads included: an upload is cut as soon as it passes the remaining space, and each file is recorded under a lock on its organization after a final check.

Encryption at rest

TaskView does not encrypt file contents itself: the API writes the bytes it received and the database keeps only metadata. Encrypt at the storage layer instead; the API does not need to know about it.

• s3 - enable server-side encryption on the bucket (SSE-S3 or SSE-KMS on AWS, SSE on MinIO). Uploads and downloads keep working unchanged.
• local - keep FILE_STORAGE_LOCAL_DIR on an encrypted disk or volume (for example LUKS on Linux). Back up the encryption key separately from the data.

This protects the files on a lost disk, a leaked backup or an exposed bucket. Anyone who can call the API with file permissions still reads the files normally - that part is governed by the project roles file_can_view and file_can_manage.

Moving files between providers

1. Add the settings of the new provider while FILE_STORAGE_PROVIDER still points to the old one.
2. Run the migration inside the API container (the CLI ships in the image next to the server bundle):

   docker exec -it <api-container> npm run files:migrate -- --from local --to s3
   

   
   Use --to local --from s3 for the reverse direction and add --goal <projectId> to move a single project. From a source checkout the same command is pnpm --filter taskview-ce-api-server build:files-migrate && pnpm --filter taskview-ce-api-server files:migrate -- --from local --to s3. The API keeps running; each file is copied, verified against its checksum, switched in the database and then removed from the old provider.
3. Switch FILE_STORAGE_PROVIDER to the new provider and restart the API.
4. Run the same command once more to pick up files uploaded between steps 2 and 3. A report of migrated: 0 means the move is complete.
5. Remove the old provider's variables.

Full example

Here's a complete .env.taskview file for a production deployment:

DB_HOST="db"
DB_USER="taskview_db_user"
DB_PASSWORD="password"
DB_NAME="taskview"
DB_PORT=5432
# Postgres connections per API worker (this is the default)
DB_POOL_MAX=20
APP_PORT=1401
# API worker processes (this is the default). Accepts a number or "max" (one worker per CPU core).
# Keep PM2_INSTANCES x DB_POOL_MAX below the Postgres max_connections limit (default 100).
PM2_INSTANCES=2
JWT_ALG="HS256"
JWT_SIGN="secret"
ACCESS_LIFE_TIME="3d"
REFRESH_LIFE_TIME="9d"

# Login methods offered on the login page (unset = all enabled)
#AUTH_LOGIN_METHODS="magic-link,password,sso,social"
# Max sign-in codes one account can request by email per hour
#LOGIN_CODE_HOURLY_LIMIT=5
# Days a sign-in session lasts, however often its tokens are refreshed
#SESSION_MAX_AGE_DAYS=90
# Password change confirmation: "email" (code by email, needs SMTP) or "password" (no SMTP needed)
#PASSWORD_CHANGE_CONFIRMATION="email"
# Air-gapped SSO: skip DNS/HTTP domain proof for these email domains
#SSO_TRUSTED_DOMAINS="company.com,corp.local"
# Let webhooks target receivers on the private network (self-hosted only)
#WEBHOOKS_ALLOW_PRIVATE_URLS=false

SMTP_HOST=smtp
SMTP_PORT=587
SMTP_USERNAME=
SMTP_PASSWORD=
SMTP_ENCRYPTION=tls
SMTP_FROM_NAME=TaskView
SMTP_FROM_EMAIL=

# Your domain 
APP_URL="https://app.taskview.tech"

GOOGLE_CLIENT_ID=""
GOOGLE_CLIENT_SECRET=""
#You domain
GOOGLE_CALLBACK_URL="https://api.taskview.tech/module/auth/provider/google/callback"
GITHUB_CLIENT_ID=""
GITHUB_CLIENT_SECRET=""
GITHUB_CALLBACK_URL="https://api.taskview.tech/module/auth/provider/github/callback"
APPLE_CLIENT_ID=""
APPLE_TEAM_ID=""
APPLE_KEY_ID=""
APPLE_KEY_LOCATION="/usr/src/app/AuthKey.p8"
# Your domain
APPLE_CALLBACK_URL="https://api.taskview.tech/module/auth/provider/apple/callback"

#integrations
GITHUB_INTEGRATION_CLIENT_ID=
GITHUB_INTEGRATION_CLIENT_SECRET=
GITHUB_INTEGRATION_CALLBACK_URL=https://api.taskview.tech/module/integrations/oauth/github/callback

GITLAB_INTEGRATION_CLIENT_ID=
GITLAB_INTEGRATION_CLIENT_SECRET=
GITLAB_INTEGRATION_CALLBACK_URL=https://api.taskview.tech/module/integrations/oauth/github/callback

ENCRYPTION_KEY=

# Messaging integrations
TELEGRAM_BOT_TOKEN=
TELEGRAM_BOT_USERNAME=
TELEGRAM_WEBHOOK_SECRET=
# SLACK_CLIENT_ID=
# SLACK_CLIENT_SECRET=
# SLACK_SIGNING_SECRET=

# Notifications (optional)
# FIREBASE_CREDENTIALS_PATH=./firebase-credentials.json
# CENTRIFUGO_API_URL=http://centrifugo:8000
# CENTRIFUGO_API_KEY=your_centrifugo_api_key
# CENTRIFUGO_TOKEN_SECRET=your_centrifugo_token_secret
# CENTRIFUGO_PUBLIC_URL=wss://api.example.com/centrifugo/connection/websocket

# Files (attachments stay disabled until a provider is configured; mount the directory as a volume)
FILE_STORAGE_PROVIDER=local
FILE_STORAGE_LOCAL_DIR=/usr/src/app/data/files
# FILE_MAX_SIZE_MB=10