docs
SELF-HOSTING

Secrets and deployment configuration

Configure your secrets and environment variables when self-hosting Phase.

Depending on your self-hosted deployment method, you may need to configure various environment variables. Certain environment variables are required, while others are optional based on your use case.

For enhanced security, Phase services support mounting secrets from files. To use this feature, specify the mount location (e.g., /run/secrets/secret_key) using the _FILE suffix naming convention (e.g., SECRET_KEY_FILE). When a file-based secret is present, services will prioritize it over any corresponding environment variable. You can enable debug mode by setting DEBUG=True to view logs indicating the source of each loaded secret.

Single sign-on (SSO)

The following providers are available:

  • google - Google OAuth 2.0
  • github - GitHub OAuth 2.0
  • gitlab - GitLab OAuth 2.0
  • authentik - Authentik OAuth 2.0
  • github-enterprise - GitHub Enterprise Server OAuth 2.0
  • google-oidc - Google OIDC
  • jumpcloud-oidc - JumpCloud OIDC
  • entra-id-oidc - Microsoft Entra ID OIDC
  • okta-oidc - Okta OIDC
  • authelia - Authelia OIDC

You can find a complete list of user auth providers here.

Google OAuth 2.0

Provider slug: google

You can find instructions for setting up SSO with Google OAuth 2.0 here.

Set the "redirect URI" for your Google OAuth application as ${HTTP_PROTOCOL}${HOST}/api/auth/callback/google.

Example:

https://[**YOUR_DOMAIN**]/api/auth/callback/google

After setting up your credentials on the Google Cloud console, set the Client ID and Client secret values:

  • Name
    GOOGLE_CLIENT_ID
    Type
    string
    Description

    Google OAuth Client ID

  • Name
    GOOGLE_CLIENT_SECRET
    Type
    string
    Description

    Google OAuth Client secret. Can be mounted from a file by suffixing _FILE to the key, pointing to a filepath.

Env(s) required by the following containers:

GitHub OAuth 2.0

Provider slug: github

You can find instructions for setting up SSO with a GitHub OAuth 2.0 App here.

Set the "Authorization callback URL" for your GitHub OAuth App as ${HTTP_PROTOCOL}${HOST}/api/auth/callback/github.

Example:

https://[**YOUR_DOMAIN**]/api/auth/callback/github

After setting up your App on GitHub, set the Client ID and Client secret values:

  • Name
    GITHUB_CLIENT_ID
    Type
    string
    Description

    GitHub OAuth Client ID

  • Name
    GITHUB_CLIENT_SECRET
    Type
    string
    Description

    GitHub OAuth Client secret. Can be mounted from a file by suffixing _FILE to the key, pointing to a filepath.

Env(s) required by the following containers:

GitHub Enterprise Server (self-hosted) OAuth 2.0

Provider slug: github-enterprise

You can find instructions for setting up SSO with a GitHub Enterprise Server OAuth 2.0 App using the same steps as GitHub OAuth, but with your enterprise instance.

Set the "Authorization callback URL" for your GitHub Enterprise Server OAuth App as ${HTTP_PROTOCOL}${HOST}/api/auth/callback/github-enterprise.

Example:

https://[**YOUR_DOMAIN**]/api/auth/callback/github-enterprise

After setting up your App on GitHub Enterprise Server, set the base URL, API URL, Client ID and Client secret values:

  • Name
    GITHUB_ENTERPRISE_BASE_URL
    Type
    string
    Description

    The URL of your GitHub Enterprise Server instance. Example: https://github.yourdomain.com

  • Name
    GITHUB_ENTERPRISE_API_URL
    Type
    string
    Description

    The API URL of your GitHub Enterprise Server instance. This is usually GITHUB_ENTERPRISE_BASE_URL + /api. Example: https://github.yourdomain.com/api. Phase will reference the environment variable and construct the API URL of your instance as follows: GITHUB_ENTERPRISE_API_URL/v3/user.

  • Name
    GITHUB_ENTERPRISE_CLIENT_ID
    Type
    string
    Description

    GitHub Enterprise Server OAuth Client ID

  • Name
    GITHUB_ENTERPRISE_CLIENT_SECRET
    Type
    string
    Description

    GitHub Enterprise Server OAuth Client secret. Can be mounted from a file by suffixing _FILE to the key, pointing to a filepath.

Env(s) required by the following containers:

GitLab OAuth 2.0

Provider slug: gitlab

You can find instructions for setting up SSO with a GitLab OAuth 2.0 Application here.

Make sure the application has the read_user scope.

You can use user-owned or group-owned applications to login to Phase. If you are running a self-hosted instance, you can also use an instance-wide application.

Set the "callback URL" for your GitLab OAuth App as ${HTTP_PROTOCOL}${HOST}/api/auth/callback/gitlab.

Example:

https://[**YOUR_DOMAIN**]/api/auth/callback/gitlab

After setting up your Application on GitLab, set the Client ID and Client secret values.

If you are using a self-hosted GitLab instance, you can optionally set the GITLAB_AUTH_URL env var.

  • Name
    GITLAB_CLIENT_ID
    Type
    string
    Description

    GitLab OAuth Client ID

  • Name
    GITLAB_CLIENT_SECRET
    Type
    string
    Description

    GitLab OAuth Client secret. Can be mounted from a file by suffixing _FILE to the key, pointing to a filepath.

  • Name
    GITLAB_AUTH_URL
    Type
    string (Optional)
    Description

    GitLab instance host url

Env(s) required by the following containers:

Authentik OAuth 2.0

Provider slug: authentik

You can find instructions for setting up SSO with an Authentik OAuth/OIDC Application here.

Set the "Redirect URI" for your Authentik OAuth/OIDC App as ${HTTP_PROTOCOL}${HOST}/api/auth/callback/authentik.

Example:

https://[**YOUR_DOMAIN**]/api/auth/callback/authentik

After setting up your Application on Authentik, set the Client ID, Client Secret, Authentik URL, and Authentik App Slug values:

  • Name
    AUTHENTIK_CLIENT_ID
    Type
    string
    Description

    Authentik OIDC Client ID

  • Name
    AUTHENTIK_CLIENT_SECRET
    Type
    string
    Description

    Authentik OIDC Client secret. Can be mounted from a file by suffixing _FILE to the key, pointing to a filepath.

  • Name
    AUTHENTIK_URL
    Type
    string
    Description

    Authentik instance URL

  • Name
    AUTHENTIK_APP_SLUG
    Type
    string
    Description

    Authentik App slug

Env(s) required by the following containers:

Authelia OIDC

Provider slug: authelia

You can find instructions for setting up SSO with an Authelia OIDC Application here.

Set the "Redirect URI" for your Authelia OIDC client as ${HTTP_PROTOCOL}${HOST}/api/auth/callback/authelia.

Example:

https://[**YOUR_DOMAIN**]/api/auth/callback/authelia

After configuring your Authelia OIDC client, set the Client ID, Client Secret, and URL values:

  • Name
    AUTHELIA_CLIENT_ID
    Type
    string
    Description

    Authelia OIDC Client ID

  • Name
    AUTHELIA_CLIENT_SECRET
    Type
    string
    Description

    Authelia OIDC Client secret. Can be mounted from a file by suffixing _FILE to the key, pointing to a filepath.

  • Name
    AUTHELIA_URL
    Type
    string
    Description

    Authelia instance URL (e.g., https://auth.example.com)

Env(s) required by the following containers:

Google OIDC

Provider slug: google-oidc

You can find instructions for setting up SSO with a Google OIDC Application here.

Set the "callback URL" for your Google OIDC App as ${HTTP_PROTOCOL}${HOST}/api/auth/callback/google-oidc.

Example:

https://[**YOUR_DOMAIN**]/api/auth/callback/google-oidc

After setting up your Application on Google Cloud, set the Client ID and Client secret values:

  • Name
    GOOGLE_OIDC_CLIENT_ID
    Type
    string
    Description

    Google OIDC Client ID

  • Name
    GOOGLE_OIDC_CLIENT_SECRET
    Type
    string
    Description

    Google OIDC Client secret. Can be mounted from a file by suffixing _FILE to the key, pointing to a filepath.

Env(s) required by the following containers:

JumpCloud OIDC

Provider slug: jumpcloud-oidc

You can find instructions for setting up SSO with a JumpCloud OIDC Application here.

Set the "callback URL" for your JumpCloud OIDC App as ${HTTP_PROTOCOL}${HOST}/api/auth/callback/jumpcloud-oidc.

Example:

https://[**YOUR_DOMAIN**]/api/auth/callback/jumpcloud-oidc

After setting up your Application on JumpCloud, set the Client ID and Client secret values:

  • Name
    JUMPCLOUD_OIDC_CLIENT_ID
    Type
    string
    Description

    JumpCloud OIDC Client ID

  • Name
    JUMPCLOUD_OIDC_CLIENT_SECRET
    Type
    string
    Description

    JumpCloud OIDC Client secret. Can be mounted from a file by suffixing _FILE to the key, pointing to a filepath.

Env(s) required by the following containers:

Microsoft Entra ID OIDC

Provider slug: entra-id-oidc

You can find instructions for setting up SSO with a Microsoft Entra ID OIDC Application here.

Set the "callback URL" for your Microsoft Entra ID OIDC App as ${HTTP_PROTOCOL}${HOST}/api/auth/callback/entra-id-oidc.

Example:

https://[**YOUR_DOMAIN**]/api/auth/callback/entra-id-oidc

After setting up your Application on Microsoft Entra ID, set the Tenant ID, Client ID and Client secret values:

  • Name
    ENTRA_ID_OIDC_TENANT_ID
    Type
    string
    Description

    Microsoft Entra ID Directory (tenant) ID

  • Name
    ENTRA_ID_OIDC_CLIENT_ID
    Type
    string
    Description

    Microsoft Entra ID Application (client) ID

  • Name
    ENTRA_ID_OIDC_CLIENT_SECRET
    Type
    string
    Description

    Microsoft Entra ID Client secret. Can be mounted from a file by suffixing _FILE to the key, pointing to a filepath.

Env(s) required by the following containers:

Okta OIDC

Provider slug: okta-oidc

You can find instructions for setting up SSO with an Okta OIDC Application here.

Set the "Sign-in redirect URIs" for your Okta OIDC App as ${HTTP_PROTOCOL}${HOST}/api/auth/callback/okta-oidc.

Example:

https://[**YOUR_DOMAIN**]/api/auth/callback/okta-oidc

After setting up your Application on Okta, set the Client ID, Client Secret and Issuer values:

  • Name
    OKTA_OIDC_CLIENT_ID
    Type
    string
    Description

    Okta OIDC Application Client ID

  • Name
    OKTA_OIDC_CLIENT_SECRET
    Type
    string
    Description

    Okta OIDC Application Client secret. Can be mounted from a file by suffixing _FILE to the key, pointing to a filepath.

  • Name
    OKTA_OIDC_ISSUER
    Type
    string
    Description

    Your Okta domain URL. Can be found in your Okta dashboard URL (e.g. https://acme-1234567.okta.com).

Env(s) required by the following containers:

Password authentication

Password authentication is opt-in for self-hosted instances. By default, Phase runs in SSO-only mode: password signup, login, change-password and password-based recovery are refused, and the login page hides the password UI. Set ENABLE_PASSWORD_AUTH=true to allow password sign-up and login alongside SSO.

  • Name
    ENABLE_PASSWORD_AUTH
    Type
    boolean (Optional)
    Description

    When set to true, password authentication is enabled alongside any configured SSO providers. Defaults to false (SSO-only).

    Accepts true, 1, or yes (case-insensitive); any other value (or an unset variable) leaves password authentication disabled.

    When disabled:

    • All password-auth endpoints (register, login, change-password, password-based recovery, email verification, resend-verification) return 403.
    • The login page hides the "Create an account" link, and /signup redirects to /login.
    • The email field on the login page remains visible -- it is the discovery mechanism for organisation-level SSO (e.g. Microsoft Entra ID), which routes users to their identity provider after they enter their work email.
    • SSO endpoints and SSO users are unaffected.

    The toggle is reversible at any time without data migration -- password hashes are preserved while disabled, and existing password users regain access if you flip it back on.

    Referenced by the frontend and backend containers.

Before enabling SSO-only mode (i.e. leaving ENABLE_PASSWORD_AUTH unset on an instance that previously had password users), make sure every member who needs continued access has signed in via SSO at least once -- the SocialAccount link is created on first SSO sign-in, and existing password users will otherwise be locked out. Configure at least one provider in SSO_PROVIDERS before disabling password auth, otherwise the instance will have no usable sign-in path.

Email verification

When SMTP is configured, new accounts must verify their email address before logging in. The verification email contains a one-time link that expires after 24 hours; if the link expires, users can request a new one from the login page.

If SMTP is not configured, or if SKIP_EMAIL_VERIFICATION is set to true, accounts are activated immediately at signup without email verification. See the email gateway configuration section below for how to wire up the mailer.

  • Name
    SKIP_EMAIL_VERIFICATION
    Type
    boolean (Optional)
    Description

    When set to true, new accounts created via email/password signup are activated immediately without requiring email verification. Defaults to false. If SMTP is not configured, email verification is automatically skipped regardless of this setting.

    Only takes effect when ENABLE_PASSWORD_AUTH is enabled.

    Referenced by the backend container.

Application secrets

  • Name
    NEXTAUTH_SECRET (Deprecated)
    Type
    string
    Description

    Deprecated. No longer read by the application after the NextAuth removal in Console v2.67.0. Safe to leave in place for now; it will be dropped from the reference deployment templates in a later release.

  • Name
    SECRET_KEY
    Type
    string
    Description

    A random 32 byte hex string. Can be generated with openssl rand -hex 32. Required by the backend and worker containers. Can be mounted from a file by suffixing _FILE to the key, pointing to a filepath.

  • Name
    SERVER_SECRET
    Type
    string
    Description

    A random 32 byte hex string. Can be generated with openssl rand -hex 32. Required by the backend and worker containers. Can be mounted from a file by suffixing _FILE to the key, pointing to a filepath.

Host configuration

  • Name
    HOST
    Type
    string
    Description

    The hostname where you would like to run Phase. Defaults to localhost. Referenced by the frontend, backend and worker containers.

  • Name
    HTTP_PROTOCOL
    Type
    string
    Description

    The url scheme for your host. Defaults to https://. Referenced by the frontend, backend and worker containers.

  • Name
    USER_EMAIL_DOMAIN_WHITELIST
    Type
    string (Optional)
    Description

    A comma-separated list of domains to restrict signups and logins. When set, only users with emails matching the specified domains can register or log in. To use this feature, set the value to a list of domains to use as a whitelist. For example:

    USER_EMAIL_DOMAIN_WHITELIST=mydomain.com,subdomain.mydomain.com

    will only allow users with emails @mydomain.com or @subdomain.mydomain.com to sign up or login. Referenced by the frontend and backend containers.

  • Name
    LOGIN_BANNER_TEXT
    Type
    string (Optional)
    Description

    A custom message to display on the login screen. Can be up to 512 characters long. This allows self-hosting users to display important information, announcements, or notices to users before they log in. Referenced by the frontend container.

Database configuration

  • Name
    DATABASE_HOST
    Type
    string
    Description

    The database hostname. Defaults to postgres.

    Required by the backend and worker containers.

  • Name
    DATABASE_NAME
    Type
    string
    Description

    Defaults to postgres-db-name.

    Required by the backend and worker containers.

  • Name
    DATABASE_USER
    Type
    string
    Description

    Defaults to postgres-user.

    Required by the backend and worker containers.

  • Name
    DATABASE_PASSWORD
    Type
    string
    Description

    A database password is provided by default, but it is highly recommended to change this value. Can be mounted from a file by suffixing _FILE to the key, pointing to a filepath.

    Required by the backend and worker containers.

  • Name
    DATABASE_PORT
    Type
    number
    Description

    Defaults to 5432.

    Required by the backend and worker containers.

  • Name
    EXTERNAL_MIGRATION
    Type
    string
    Description

    Defaults to false. This is used to control whether the backend container will run database migrations. In a standalone (monolith) deployment setup, you may set this to false or use the default value to automatically run the database migrations. In high availability systems (such as Kubernetes, Docker Swarm, Nomad) where multiple replicas of the service is bring run concurrently, please set it to true and handle the migrations in an a dedicated job for a safe and reliable migration setup.

    Referenced by the backend container.

  • Name
    DATABASE_SSL
    Type
    boolean
    Description

    Enables or disables SSL/TLS for database connections. Defaults to False.

    When False or unset, Phase uses the default sslmode=prefer, which attempts a TLS connection but falls back to plaintext if TLS is unavailable. When True, Phase enforces a TLS connection.

    Required by the backend and worker containers.

  • Name
    DATABASE_SSL_CA_PATH
    Type
    string (Optional)
    Description

    Path to the CA certificate bundle for verifying the database's TLS certificate.

    If provided, Phase sets sslmode=verify-full and validates the database certificate against this CA, including a hostname check. If not provided (but DATABASE_SSL=True), Phase sets sslmode=require.

    For AWS RDS, Phase includes the RDS CA bundle at /etc/ssl/certs/rds-ca-bundle.pem which you can point this variable to.

    Required by the backend and worker containers.

Redis configuration

Phase uses Redis or Valkey for a synchronous jobs queues, caching and rate limiting.

If your Redis or Valkey instance support ACLs, make sure it's set up with at least on ~* -@all +@read +@write +ping +multi +exec +discard +watch +unwatch +@scripting access string (ACL) permissions.

  • Name
    REDIS_HOST
    Type
    string
    Description

    The Redis server hostname. Defaults to redis.

    Required by the backend and worker containers.

  • Name
    REDIS_PORT
    Type
    number
    Description

    The Redis server port. Defaults to 6379.

    Required by the backend and worker containers.

  • Name
    REDIS_PASSWORD
    Type
    string
    Description

    The password for the Redis server. Can be mounted from a file by suffixing _FILE to the key, pointing to a filepath.

    Required by the backend and worker containers.

  • Name
    REDIS_SSL
    Type
    boolean
    Description

    Enables or disables SSL for Redis connections. Defaults to False.

    The value is considered True if the environment variable is set to "true" (case-insensitive).

    Required by the backend and worker containers.

  • Name
    REDIS_USER
    Type
    string (Optional)
    Description

    The username for the Redis server. Required if your Redis instance has ACLs enabled.

    Required by the backend and worker containers.

  • Name
    REDIS_SSL_CA_PATH
    Type
    string (Optional)
    Description

    Path to the CA certificate bundle for verifying Redis SSL certificates. Required if REDIS_SSL is set to True. Example: /etc/ssl/certs/ca-certificates.crt If you using a self-signed certificate, you can set this to the path to the certificate bundle. Sames goes for a certificate bundle for a managed service like Redis Cloud which may not be available in the default certificate bundle. Required by the backend and worker containers.

Email gateway configuration

SMTP configuration is required for email verification for password-based signup. If SMTP is not configured, new accounts created via email/password are activated immediately without email verification.

  • Name
    SMTP_SERVER
    Type
    string
    Description

    Your SMTP gateway host. eg. my-email-gateway-smtp.eu-central-1.amazonaws.com

    Referenced by the backend and worker containers.

  • Name
    SMTP_PORT
    Type
    number
    Description

    The port for your SMTP server. Defaults to 587, if not specified.

    Referenced by the backend and worker containers.

  • Name
    SMTP_USERNAME
    Type
    string
    Description

    Your SMTP email gateway username.

    Referenced by the backend and worker containers.

  • Name
    SMTP_PASSWORD
    Type
    string
    Description

    Your SMTP email gateway password. Can be mounted from a file by suffixing _FILE to the key, pointing to a filepath.

    Referenced by the backend and worker containers.

  • Name
    DEFAULT_FROM_EMAIL
    Type
    string
    Description

    Email address from which you want to dispatch emails.

    Referenced by the backend and worker containers.

  • Name
    SMTP_TIMEOUT
    Type
    number
    Description

    The timeout in seconds for SMTP operations. Defaults to 5, if not specified.

    Referenced by the backend and worker containers.

  • Name
    SMTP_USE_TLS
    Type
    boolean
    Description

    Enables or disables TLS (Transport Layer Security) for SMTP connections. Defaults to True.

    The value is considered True if the environment variable is set to "true" or "1" (case-insensitive).

    Note: Only one of SMTP_USE_TLS or SMTP_USE_SSL should be enabled.

    Referenced by the backend and worker containers.

  • Name
    SMTP_USE_SSL
    Type
    boolean
    Description

    Enables or disables SSL (Secure Sockets Layer) for SMTP connections. Defaults to False.

    The value is considered True if the environment variable is set to "true" or "1" (case-insensitive).

    Note: Only one of SMTP_USE_TLS or SMTP_USE_SSL should be enabled.

    Referenced by the backend and worker containers.

Email Logging

When sending emails, Phase logs the following information:

  • Successful emails: Debug level logs that include the email subject and recipient list (Please set DEBUG=True to see these logs)
  • SMTP errors: Error level logs that include the recipient list and detailed SMTP error message e.g. 535 Authentication credentials invalid
  • Unexpected errors: Error level logs that include the recipient list and error message e.g. SMTP timeouts, connection errors, etc.

These logs can be useful for troubleshooting email delivery issues when self-hosting.

Third party integrations configuration

GitHub integration:

  1. Create a new GitHub OAuth application. You may follow the instructions here. Please note that this is different from the one you may already have set up for GitHub SSO, which is used for authentication.
  2. Set the Authorization callback URL to: https://[**YOUR_DOMAIN**]/service/oauth/github/callback
  3. Hit Register application
  4. Supply the following secrets to your Phase Console instance
  • Name
    GITHUB_INTEGRATION_CLIENT_ID
    Type
    string
    Description

    GitHub OAuth application Client ID

    Referenced by the frontend and backend containers.

  • Name
    GITHUB_INTEGRATION_CLIENT_SECRET
    Type
    string
    Description

    GitHub OAuth application Client Secret. Can be mounted from a file by suffixing _FILE to the key, pointing to a filepath.

    Referenced by the backend container.

GitHub Enterprise Server (self-hosted) integration:

  1. Create a new GitHub Enterprise Server OAuth application. You may follow the instructions here. Please note that this is different from the one you may already have set up for GitHub SSO, which is used for authentication.
  2. Set the Authorization callback URL to: https://[**YOUR_DOMAIN**]/service/oauth/github/callback
  3. Click "Register application"
  4. Supply the following secrets to your Phase Console instance
  • Name
    GITHUB_ENTERPRISE_INTEGRATION_CLIENT_ID
    Type
    string
    Description

    GitHub Enterprise Server OAuth application Client ID

    Referenced by the frontend and backend containers.

  • Name
    GITHUB_ENTERPRISE_INTEGRATION_CLIENT_SECRET
    Type
    string
    Description

    GitHub Enterprise Server OAuth application Client Secret. Can be mounted from a file by suffixing _FILE to the key, pointing to a filepath.

    Referenced by the backend container.

AWS Integration

Assume Role

Choose a method of supplying AWS integration credentials to your Phase instance.

If you are running Phase inside of a container(s) on an AWS EC2 instance, you can use an EC2 instance profile to provision a machine role which Phase will use via the IMDSv2 API to assume other roles to get temporary credentials.

Step 1: Create IAM Policy

Create an IAM policy:

aws iam create-policy --policy-name PhaseGlobalAssumeRolePolicy --policy-document '{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowAssumeAnyRole",
      "Effect": "Allow",
      "Action": "sts:AssumeRole",
      "Resource": "arn:aws:iam::*:role/*"
    }
  ]
}'

Step 2: Create IAM role

aws iam create-role --role-name PhaseEC2InstanceRole --assume-role-policy-document '{
  "Version":"2012-10-17",
  "Statement":[
    {
      "Effect":"Allow",
      "Principal":{"Service":"ec2.amazonaws.com"},
      "Action":"sts:AssumeRole"
    }
  ]
}'

Step 3: Attach the policy to the role

aws iam attach-role-policy --role-name PhaseEC2InstanceRole --policy-arn <POLICY_ARN>

Step 4: Create an IAM instance profile

aws iam create-instance-profile --instance-profile-name PhaseEC2InstanceRole

Step 5: Add the role to the instance profile

aws iam add-role-to-instance-profile --instance-profile-name PhaseEC2InstanceRole --role-name PhaseEC2InstanceRole

Make sure this instance profile is attached to the EC2 instance(s) that will be used to run Phase.

Please make sure that the instance metadata service is enabled, and IMDSv2 is enabled and reachable from within the containers.

Depending on how you first created the EC2 instance, you may have to enable IMDSv2 manually and set the metadata response hop limit to 2. This is the default when creating an EC2 from the AWS Console launch wizard. You can use the following command to set the metadata response hop limit to 2. Make sure that you have the ec2:ModifyInstanceMetadataOptions permission before running it:

aws ec2 modify-instance-metadata-options --instance-id YOUR_INSTANCE_ID --http-put-response-hop-limit 2 --http-endpoint enabled --region YOUR_AWS_REGION_IF_NEEDED

Sample output:

{
    "InstanceId": "i-12f345f5d7890fb11",
    "InstanceMetadataOptions": {
        "State": "pending",
        "HttpTokens": "optional",
        "HttpPutResponseHopLimit": 2,
        "HttpEndpoint": "enabled",
        "HttpProtocolIpv6": "disabled",
        "InstanceMetadataTags": "disabled"
    }
}

License

Phase requires a valid license to use the Enterprise tier features in self-hosted deployments. You can request a free trial license here.

Offline license

For air-gapped or restricted-egress environments, use the PHASE_LICENSE_OFFLINE variable.

Phase does not export any outbound usage telemetry for self-hosted instances. This license will work in fully air-gapped environments or where egress is filtered.

  • Name
    PHASE_LICENSE_OFFLINE
    Type
    string
    Description

    The environment variable Phase license for self-hosted deployments with egress restrictions. Can be mounted from a file by suffixing _FILE to the key, pointing to a filepath Example: phase_license:v1:... Referenced by the backend and worker containers.

The backend logs license validation details on every startup:

phase-backend  | License is valid.
phase-backend  | License ID: e3de75b1-9afc-4ec1-a203-18febd7be2c0, Customer Name: SpaceX, Tier: ENTERPRISE, Expiry: 2080-01-01

Debugging

  • Name
    DEBUG
    Type
    string (optional)
    Description

    Allows running the application with "Debug mode" enabled. Provide this environment variable with the value True to enable this.

    Never run the application with Debug mode enabled in production!

Env(s) required by the following containers:

Additional Environment Variables

These variables are not required if using the suggested docker-compose template. However if you are deploying the Phase Console using a custom docker-compose configuration or without docker-compose, make sure the following variables are correctly set.

  • Name
    NEXTAUTH_URL
    Type
    string
    Description

    The base console URL for NextAuth. References ${HTTP_PROTOCOL}${HOST}

    Example: https://[**YOUR_DOMAIN**]

    Required by the frontend container.

  • Name
    OAUTH_REDIRECT_URI
    Type
    string
    Description

    The base console URI, used for OAuth redirection from backend to frontend. References ${HTTP_PROTOCOL}${HOST}

    Example: https://[**YOUR_DOMAIN**]

    Required by the backend container.

  • Name
    BACKEND_API_BASE
    Type
    string
    Description

    The base URL for the backend API. This will be accessed privately by the Phase frontend container. You may use a private, non publicly accessible url like http://backend:8000 to avoid over the internet roundtrip for performance reasons. References ${HTTP_PROTOCOL}${HOST}/service

    Example: https://[**YOUR_DOMAIN**]/service

    Required by the frontend container.

  • Name
    NEXT_PUBLIC_BACKEND_API_BASE
    Type
    string
    Description

    The public base URL for the backend API. This URL will be accessed publicly by the browser running Phase Console. References ${HTTP_PROTOCOL}${HOST}/service

    Example: https://[**YOUR_DOMAIN**]/service

    Required by the frontend container.

  • Name
    SSO_PROVIDERS
    Type
    string (Optional)
    Description

    Comma-separated list of SSO providers.

    Example: google,github,gitlab

    Referenced by the frontend container.

  • Name
    NEXT_PUBLIC_NEXTAUTH_PROVIDERS (Legacy)
    Type
    string
    Description

    This is a legacy variable and is not required if you using Console version >= v2.50.0

    Comma-separated list of NextAuth providers. References ${SSO_PROVIDERS}

    Example: google,github,gitlab

    Required by the frontend container.

  • Name
    ALLOWED_HOSTS
    Type
    string
    Description

    Comma-separated list of allowed hosts used the backend. Default: ${HOST},backend

    Example: [**YOUR_DOMAIN**],backend

    Required by the backend and worker containers.

  • Name
    ALLOWED_ORIGINS
    Type
    string
    Description

    Comma-separated list of allowed origins used by the Phase backend. References ${HTTP_PROTOCOL}${HOST}

    Example: https://[**YOUR_DOMAIN**]

    Required by the backend and worker containers.

  • Name
    SESSION_COOKIE_DOMAIN
    Type
    string
    Description

    Domain for the session cookie used by the Phase backend. References ${HOST}

    Example: [**YOUR_DOMAIN**] (example.com)

    Required by the backend and worker containers.

  • Name
    GUNICORN_WORKERS
    Type
    number (Optional)
    Description

    The number of Gunicorn worker processes for handling requests in the backend. If not specified, Phase will automatically calculate the number of workers based on available CPU cores using the formula (2 * CPUs) + 1, with a default cap of 8 workers to prevent potential database connection exhaustion.

    Referenced by the backend container.

  • Name
    RATE_LIMIT_DEFAULT
    Type
    string
    Description

    Rate limit for API requests. Example: 100/minute. Rate limits can be specified over a period of second, minute, hour or day. The period must be specified after the / separator using s, m, h or d, respectively. For increased clarity, extended units such as second, minute, hour, day or even abbreviations like sec, min, hr are allowed, as only the first character is relevant to identify the rate. Referenced by the backend and worker containers.