> ## Documentation Index
> Fetch the complete documentation index at: https://darkbanner.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Environment variables and settings for deploying and configuring Zygo

Zygo is configured entirely through environment variables. This page documents every available setting, organized by category.

## Core Application

| Variable | Default | Description |
| - | - | - |
| `APP_NAME` | `Zygo` | Application name displayed in the UI and emails |
| `APP_SUBTITLE` | *(empty)* | Optional subtitle shown alongside the app name |
| `VERSION` | `1.0.0` | Application version string |
| `CR_YEAR` | `2026` | Copyright year displayed in the footer |
| `HOST_NAME` | `localhost` | The public URL of your Zygo instance (e.g., `https://app.zygo.com`). Used for generating links in emails and form URLs. |
| `SECRET_KEY` | `change_secret_key` | Secret key for signing sessions and tokens. **Must be changed in production.** |
| `DOC_LINK` | *(empty)* | URL to your documentation, shown in the UI |

> [!WARNING]
>
> Always set a strong, unique `SECRET_KEY` in production. The default value is insecure and will allow session forgery.

## Database

Zygo uses PostgreSQL as its primary database.

| Variable | Default | Description |
| - | - | - |
| `SQLALCHEMY_DATABASE_URI` | `postgresql://db1:db1@postgres/db1` | Full PostgreSQL connection string |

The connection string follows the standard format:

```
postgresql://username:password@host:port/database
```

> [!NOTE]
>
> The host, username, password, and database name are automatically parsed from the connection string. You only need to set `SQLALCHEMY_DATABASE_URI`.

## Redis

Redis is used for background job queues and rate limiting.

| Variable | Default | Description |
| - | - | - |
| `REDIS_URL` | `redis://localhost:6379/0` | Redis connection string. Also used as the rate limit storage backend. |

## Authentication

### Sessions

| Variable | Default | Description |
| - | - | - |
| `PERMANENT_SESSION_LIFETIME` | `10` | Browser session lifetime in hours. After this period, the user must log in again. |

### Default Admin Account

| Variable | Default | Description |
| - | - | - |
| `DEFAULT_EMAIL` | `admin@example.com` | Email for the default admin account created on first run |
| `DEFAULT_PASSWORD` | `admin1234567` | Password for the default admin account |
| `HELP_EMAIL` | *(same as DEFAULT\_EMAIL)* | Contact email shown in help/support contexts |

> [!WARNING]
>
> Change `DEFAULT_EMAIL` and `DEFAULT_PASSWORD` before your deployment. By default, you will need to update the password when you first login.

### Self-Registration

| Variable | Default | Description |
| - | - | - |
| `ENABLE_SELF_REGISTRATION` | `false` | Allow new users to create accounts without an invitation. Requires email to be configured. |

### OAuth / Social Login

> [tab] Google
>
> | Variable | Default | Description |
> | - | - | - |
> | `ENABLE_GOOGLE_AUTH` | `false` | Enable "Sign in with Google" |
> | `GOOGLE_CLIENT_ID` | *(none)* | OAuth 2.0 Client ID from Google Cloud Console |
> | `GOOGLE_CLIENT_SECRET` | *(none)* | OAuth 2.0 Client Secret |
>
> To set up Google authentication:
>
> 1. Create a project in the [Google Cloud Console](https://console.cloud.google.com/)
> 2. Configure the OAuth consent screen
> 3. Create OAuth 2.0 credentials
> 4. Add your Zygo callback URL as an authorized redirect URI

> [tab] Microsoft
>
> | Variable | Default | Description |
> | - | - | - |
> | `ENABLE_MICROSOFT_AUTH` | `false` | Enable "Sign in with Microsoft" |
> | `MICROSOFT_CLIENT_ID` | *(none)* | Application (client) ID from Azure AD |
> | `MICROSOFT_CLIENT_SECRET` | *(none)* | Client secret from Azure AD |
>
> To set up Microsoft authentication:
>
> 1. Register an application in [Azure Active Directory](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps)
> 2. Add a client secret
> 3. Configure the redirect URI to point to your Zygo instance

## Encryption

| Variable | Default | Description |
| - | - | - |
| `FERNET_KEY` | *(built-in default)* | Fernet symmetric encryption key used to encrypt credentials and sensitive data at rest. Must be a valid URL-safe base64-encoded 32-byte key. |

Generate a new key:

```bash theme={null}
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
```

> [!WARNING]
>
> If you change the `FERNET_KEY` after storing credentials, all previously encrypted data becomes unreadable. Back up and re-encrypt before rotating.

## Email

Zygo sends transactional emails for account confirmation, password resets, notifications, and tenant invitations. Two providers are supported.

| Variable | Default | Description |
| - | - | - |
| `EMAIL_PROVIDER` | `smtp` | Email provider: `smtp` or `mailjet` |

> [tab] SMTP
>
> | Variable | Default | Description |
> | - | - | - |
> | `MAIL_SERVER` | `smtp.googlemail.com` | SMTP server hostname |
> | `MAIL_PORT` | `587` | SMTP server port |
> | `MAIL_USE_TLS` | `true` | Enable TLS encryption |
> | `MAIL_USERNAME` | *(none)* | SMTP username |
> | `MAIL_PASSWORD` | *(none)* | SMTP password |
> | `MAIL_DEFAULT_SENDER` | *(same as DEFAULT\_EMAIL)* | "From" address on outgoing emails |
> | `MAIL_DEBUG` | `false` | Log SMTP protocol details for debugging |

> [tab] Mailjet
>
> | Variable | Default | Description |
> | - | - | - |
> | `MAILJET_API_KEY` | *(empty)* | Mailjet API key |
> | `MAILJET_API_SECRET` | *(empty)* | Mailjet API secret |
> | `MAIL_DEFAULT_SENDER` | *(same as DEFAULT\_EMAIL)* | "From" address on outgoing emails |

## Internal API

| Variable | Default | Description |
| - | - | - |
| `INTERNAL_API_SECRET` | `internal-secret-change-me` | Shared secret for authenticating requests from internal workers (e.g., background job callbacks). Passed via `X-Internal-Secret` header. |

> [!WARNING]
>
> Change `INTERNAL_API_SECRET` in production. The default value is publicly known.

## Logging

| Variable | Default | Description |
| - | - | - |
| `LOG_TYPE` | `stream` | Log output type |
| `LOG_LEVEL` | `INFO` | Minimum log level: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` |
| `ENABLE_GCP_LOGGING` | `false` | Enable Google Cloud Platform structured logging |

## Debugging

| Variable | Default | Description |
| - | - | - |
| `DEBUG_ENV_VARS` | `STORAGE_METHOD` | Comma-separated list of environment variable names to expose in the frontend for debugging. **Do not include sensitive values.** |

## Environments

Zygo ships with three configuration profiles. The active profile is set at startup.

> [accordion] production (default)
>
> * Debug mode: **off**
> * Use for all live deployments
> * Set via: `FLASK_CONFIG=default` or omit (default)

> [accordion] development
>
> * Debug mode: **on**
> * Hot reloading and verbose error pages
> * Set via: `FLASK_CONFIG=development`

> [accordion] testing
>
> * Debug mode: **on**
> * CSRF protection: **disabled**
> * Use for automated test suites
> * Set via: `FLASK_CONFIG=testing`

All three profiles share the same configuration variables — the only differences are `DEBUG`, `TESTING`, and `WTF_CSRF_ENABLED`.

## Minimal Production Setup

The minimum environment variables you need to set for a production deployment:

```bash theme={null}
# Required — security
SECRET_KEY=your-strong-random-secret-key
FERNET_KEY=your-generated-fernet-key
INTERNAL_API_SECRET=your-internal-secret

# Required — infrastructure
SQLALCHEMY_DATABASE_URI=postgresql://user:pass@dbhost:5432/zygo
REDIS_URL=redis://redis-host:6379/0
HOST_NAME=https://app.yourcompany.com

# Required — admin account
DEFAULT_EMAIL=admin@yourcompany.com
DEFAULT_PASSWORD=a-strong-initial-password

# Required — email (pick one provider)
EMAIL_PROVIDER=smtp
MAIL_SERVER=smtp.yourprovider.com
MAIL_USERNAME=your-smtp-user
MAIL_PASSWORD=your-smtp-password
MAIL_DEFAULT_SENDER=noreply@yourcompany.com
```

> [!TIP]
>
> After first deployment, log in with the default admin credentials, change the password immediately, and then configure tenants and invite your team.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.