WARNING

This page is for configuring your deployment.

To find out more about configuring the GiiS app, checkout our Admin docs!

Configuring GiiS Deployments

GiiS offers a wide range of deployment-level configuration options. These are controlled via environment variables or through your deployment files.

GiiS Lite

GiiS Lite is a minimal deployment of GiiS designed for teams that only need the core LLM chat experience without connectors or RAG search. It is ideal for resource-constrained environments, quick evaluations, or use cases where you want to bring your own LLM and tools without ingesting external data sources.

What's Included

GiiS Lite retains the following capabilities:

• LLM chat conversations
• Tools (including code interpreter in Docker deployments)
• User file uploads
• Projects
• Agent knowledge
• Assistants (without RAG retrieval)

What's Removed

To reduce resource requirements, GiiS Lite disables:

• Vespa (vector database) — no document indexing or RAG search
• Redis — PostgreSQL is used for caching and session management instead
• Model servers — no local embedding models (LLM inference is handled by your configured provider)
• Celery background workers — the API server handles background work directly
• MinIO / S3 file storage — PostgreSQL is used for file storage instead
• Connectors — all data source connectors are disabled

How It Works

GiiS Lite is not a separate application. It uses the same GiiS images with a different configuration that consolidates all storage onto PostgreSQL and disables the vector database. The key environment variables that drive this are:

Variable	Lite Value	Full GiiS Default	Purpose
DISABLE_VECTOR_DB	true	false	Disables Vespa, connectors, and RAG search
CACHE_BACKEND	postgres	redis	Uses PostgreSQL for caching instead of Redis
AUTH_BACKEND	postgres	redis	Uses PostgreSQL for sessions instead of Redis
FILE_STORE_BACKEND	postgres	s3	Uses PostgreSQL for file storage instead of S3/MinIO

INFO

GiiS Lite cannot be used with the Craft feature (ENABLE_CRAFT).

If you don't have a `.env` file:

```bash
cd giis/deployment/docker_compose
cp env.prod.template .env

# If applicable
cp env.nginx.template .env.nginx
```

The template files have a subset of common environment variables provided for you.
You can add more environment variables (listed below) to these `.env` files.

Some configuration options must be set in your Docker Compose file.

::: info

The Docker Compose file you use to launch GiiS is the one you will need to modify. Likely either docker-compose.dev.yml or docker-compose.prod.yml.

Deploying GiiS Lite with Docker Compose

GiiS Lite is deployed using a Docker Compose override file that layers on top of your base Compose file.
The override moves non-essential services (Vespa, Redis, model servers, background workers)
into Docker Compose [profiles](https://docs.docker.com/compose/how-tos/profiles/) so they do not start by default.

**Quick start:**

```bash
cd giis/deployment/docker_compose
docker compose -f docker-compose.yml -f docker-compose.giis-lite.yml up -d
```

With development ports exposed:

```bash
docker compose -f docker-compose.yml -f docker-compose.giis-lite.yml \
               -f docker-compose.dev.yml up -d --wait
```

Services started in Lite mode:
| Service | Description |
|------------------|-----------------------------------|
| api_server | GiiS API server (also handles background work) |
| web_server | Next.js frontend |
| relational_db | PostgreSQL database |
| nginx | Reverse proxy |
Services not started (moved to profiles):
| Service | Profile | Bring back with |
|--------------------------|----------------|-----------------------------------------|
| background (Celery) | background | --profile background (also needs --profile redis) |
| cache (Redis) | redis | --profile redis |
| index (Vespa) | vectordb | --profile vectordb |
| indexing_model_server | vectordb | --profile vectordb |
| inference_model_server | inference | --profile inference |
::: tip
  You can selectively bring services back by adding `--profile <name>` flags. For example, to run Lite with Redis:

```bash
docker compose -f docker-compose.yml -f docker-compose.giis-lite.yml \
            --profile redis up -d
```

::: info

The .env file setup is the same as a standard Docker deployment. Lite-specific environment variables (DISABLE_VECTOR_DB, CACHE_BACKEND, AUTH_BACKEND, FILE_STORE_BACKEND) are set automatically by the override file — you do not need to add them to your .env. :::

Kubernetes deployments are configured using Helm charts.
We have provided a `values.yaml` file where you can set all environment variables.

```bash
cd giis/deployment/helm/charts/giis
vim values.yaml
```

Add environment variables and secrets to the `configMap` and `auth.secrets` sections.
A subset of common configuration options are provided for you. You can add more environment variables (listed below)
to these sections.

Deploying GiiS Lite with Helm

GiiS Lite is deployed by providing the values-lite.yaml file when installing the Helm chart.
This values file disables the vector database, Redis, and all Celery workers, leaving only the API server,
web server, and PostgreSQL. Quick start:

```
helm install giis ./deployment/helm/charts/giis \
  -f ./deployment/helm/charts/giis/values-lite.yaml
```

To merge with your own overrides (custom domain, auth, LLM config, etc.):

```
  helm install giis ./deployment/helm/charts/giis \
-f ./deployment/helm/charts/giis/values-lite.yaml \
-f my-overrides.yaml
```

::: tip

You can always upgrade from Lite to a full deployment later by re-installing with the default values.yaml (without values-lite.yaml). This will bring up Opensearch, Redis, and all background workers. :::

TIP

Many configuration options are available in the Admin Panel! This page only covers deployment-level configuration.

Commonly Configured Options

Authentication

Set up email and password authentication.

Authenticate with Google accounts.

Single-sign on with OpenID Connect (OIDC)

Single-sign on with Security Assertion Markup Language (SAML)

Custom Domain

To host GiiS on a custom domain, set the WEB_DOMAIN environment variable and update your DNS records to point to your public GiiS deployment IP.

For additional instructions, read the EC2 Deployment Guide!

SSL

If using Docker, the init-letsencrypt.sh script in giis/deployment/docker_compose will automatically generate a Let's Encrypt certificate and launch GiiS with SSL enabled.

Web Search

To enable the Web Search Tool, set the EXA_API_KEY environment variable.

INFO

Web Search in GiiS is continually developing and these instructions will be updated as we make improvements.

Logging

When self-hosting GiiS, you can configure the level of detail in the logs. This is helpful when troubleshooting issues.

If using Docker, set LOG_LEVEL to debug in each container of your Docker Compose file.

If using Kubernetes, set LOG_LEVEL to debug in your values.yaml file.

Observability

You can connect your observability tools to GiiS. We support the following providers:

Braintrust (recommended)

Braintrust is what we use internally for the cloud version of GiiS. Set the following environment variables:

BRAINTRUST_PROJECT="Your project name"
BRAINTRUST_API_KEY="sk-..."

Langfuse

LANGFUSE_SECRET_KEY="sk-..."
LANGFUSE_PUBLIC_KEY="pk-..."
LANGFUSE_BASE_URL="https://cloud.langfuse.com" # Or "https://us.cloud.langfuse.com"

GiiS Environment Variables

INFO

This is not an exhaustive list of all GiiS environment variables.

`SKIP_WARM_UP`: Skip application warm-up process for hot-reloading the `API server`.
Only set this for development purposes.

`WEB_DOMAIN`: Set this if you are deploying GiiS on a custom domain.

`DISABLE_GENERATIVE_AI`: Disable generative AI features.

`DISABLE_USER_KNOWLEDGE`: Controls whether users can use the My Documents feature with assistants.

`GIIS_QUERY_HISTORY_TYPE`: Controls query history reports (show user emails, anonymous, no queries)

`AUTH_TYPE`: Authentication type (disabled, basic, oauth, etc.)

`PASSWORD_MIN_LENGTH`: For basic auth. The minimum password length requirement

`PASSWORD_MAX_LENGTH`: For basic auth. The maximum password length requirement

`PASSWORD_REQUIRE_UPPERCASE`: For basic auth. Require uppercase letters in passwords

`PASSWORD_REQUIRE_LOWERCASE`: For basic auth. Require lowercase letters in passwords

`PASSWORD_REQUIRE_DIGIT`: For basic auth. Require digits in passwords

`PASSWORD_REQUIRE_SPECIAL_CHAR`: For basic auth. Require special characters in passwords

`ENCRYPTION_KEY_SECRET`: Enterprise Edition only. Key for encrypting connector credentials, API keys, etc.

`MASK_CREDENTIAL_PREFIX`: Mask connector credentials in the admin UI.
Turn off if admins should see the credentials in the admin panel.

`SESSION_EXPIRE_TIME_SECONDS`: Session expiration time in seconds.

`AUTH_COOKIE_EXPIRE_TIME_SECONDS`: JWT token validity duration in seconds.

`VALID_EMAIL_DOMAINS`: Comma-separated list of allowed email domains.

`REQUIRE_EMAIL_VERIFICATION`: Require email verification for registration

`TRACK_EXTERNAL_IDP_EXPIRY`: Honor the `expires_at` field returned by the external identity provider.
Disabled be default because many auth providers have very short expiry times.

`OAUTH_CLIENT_ID`: For both Google OAuth and OIDC.

`OAUTH_CLIENT_SECRET`: For both Google OAuth and OIDC.

`OPENID_CONFIG_URL`: For OIDC.

`GOOGLE_OAUTH_SCOPE_OVERRIDE`: For Google OAuth login (`AUTH_TYPE=google_oauth` or `cloud`).
Comma-separated list of scopes to request from Google instead of the defaults (`openid,email,profile`).
Useful when the access token from login needs to be passed through to tool calls that require additional Google API
scopes (i.e. when using Pass-Through OAuth for an MCP server).
Any scopes added here must also be enabled on the OAuth client in Google Cloud Console.

`OIDC_SCOPE_OVERRIDE`: For OIDC login (`AUTH_TYPE=oidc`).
Comma-separated list of scopes to request from the OIDC provider instead of the defaults.
Same use case as `GOOGLE_OAUTH_SCOPE_OVERRIDE`.

`OIDC_PKCE_ENABLED`: For OIDC login. Set to `true` to enable PKCE in the OIDC login flow.
Disabled by default for backwards compatibility.

::: info

Set the following for basic auth email verification and invites.

`SMTP_SERVER`: SMTP server hostname

`SMTP_PORT`: SMTP server port

`SMTP_USER`: SMTP username

`SMTP_PASS`: SMTP password

`EMAIL_FROM`: From email address

`SENDGRID_API_KEY`: Alternative to SMTP for email delivery.

`ENABLE_EMAIL_INVITES`: Enable email invitations

`OAUTH_SLACK_CLIENT_ID`: Slack OAuth client ID for Slack bot.

`OAUTH_SLACK_CLIENT_SECRET`: Slack OAuth client secret for Slack bot.

`POSTGRES_USER`: PostgreSQL username

`POSTGRES_PASSWORD`: PostgreSQL password

`POSTGRES_HOST`: PostgreSQL host

`POSTGRES_PORT`: PostgreSQL port

`POSTGRES_DB`: PostgreSQL database name

`POSTGRES_API_SERVER_POOL_SIZE`: API server connection pool size

`POSTGRES_API_SERVER_POOL_OVERFLOW`: API server pool overflow

`POSTGRES_API_SERVER_READ_ONLY_POOL_SIZE`: Read-only pool size

`POSTGRES_API_SERVER_READ_ONLY_POOL_OVERFLOW`: Read-only pool overflow

`POSTGRES_USE_NULL_POOL`: Use null connection pool

`POSTGRES_POOL_PRE_PING`: Enable connection pre-ping

`POSTGRES_POOL_RECYCLE`: Pool recycle timeout in seconds

`USE_IAM_AUTH`: Use IAM authentication for database

`DB_READONLY_USER`: Read-only database user

`DB_READONLY_PASSWORD`: Read-only database password

`REDIS_SSL`: Enable SSL for Redis connections

`REDIS_HOST`: Redis host

`REDIS_PORT`: Redis port

`REDIS_PASSWORD`: Redis password

`REDIS_REPLICA_HOST`: Redis replica host

`REDIS_DB_NUMBER`: Redis database number

`REDIS_DB_NUMBER_CELERY_RESULT_BACKEND`: Celery result backend database number

`REDIS_DB_NUMBER_CELERY`: Celery broker database number

`REDIS_HEALTH_CHECK_INTERVAL`: Health check interval

`REDIS_POOL_MAX_CONNECTIONS`: Maximum pool connections

`REDIS_SSL_CERT_REQS`: SSL certificate requirements

`REDIS_SSL_CA_CERTS`: SSL CA certificates

`VESPA_HOST`: Vespa host

`VESPA_CONFIG_SERVER_HOST`: Vespa config server host

`VESPA_PORT`: Vespa port

`VESPA_TENANT_PORT`: Vespa tenant port

`NUM_RETRIES_ON_STARTUP`: Startup connection attempts

`VESPA_CLOUD_URL`: Vespa Cloud URL

`VESPA_CLOUD_CERT_PATH`: Vespa Cloud certificate path

`VESPA_CLOUD_KEY_PATH`: Vespa Cloud key path

`MANAGED_VESPA`: Use managed Vespa (Vespa Cloud)

`VESPA_REQUEST_TIMEOUT`: Request timeout in seconds

`VESPA_LANGUAGE_OVERRIDE`: Force Vespa language (en, de, etc.)

`CELERY_RESULT_EXPIRES`: Result expiration time in seconds

`CELERY_BROKER_POOL_LIMIT`: Broker connection pool limit

`CELERY_WORKER_LIGHT_CONCURRENCY`: Light worker concurrency

`CELERY_WORKER_LIGHT_PREFETCH_MULTIPLIER`: Light worker prefetch multiplier

`CELERY_WORKER_DOCPROCESSING_CONCURRENCY`: Document processing worker concurrency

`CELERY_WORKER_DOCFETCHING_CONCURRENCY`: Document fetching worker concurrency

`CELERY_WORKER_KG_PROCESSING_CONCURRENCY`: Knowledge graph processing worker concurrency

::: info

These rate limits apply to auth endpoints :::

`RATE_LIMIT_WINDOW_SECONDS`: Rate limiting window in seconds

`RATE_LIMIT_MAX_REQUESTS`: Maximum requests per window

`REQUEST_TIMEOUT_SECONDS`: Default request timeout

`INDEX_BATCH_SIZE`: Batch size during indexing

`DISABLE_INDEX_UPDATE_ON_SWAP`: Disable primary index updates during embedding model swaps

`ENABLE_MULTIPASS_INDEXING`: Enable multipass indexing for better accuracy

`ENABLE_CONTEXTUAL_RAG`: Enable contextual retrieval

`SKIP_METADATA_IN_CHUNK`: Skip metadata in chunks

`INDEXING_SIZE_WARNING_THRESHOLD`: Size warning threshold in bytes

`INDEXING_EMBEDDING_MODEL_NUM_THREADS`: Embedding model threads

`CONTINUE_ON_CONNECTOR_FAILURE`: Continue indexing on connector failures

`MAX_DOCUMENT_CHARS`: Maximum document characters

`MAX_FILE_SIZE_BYTES`: Maximum file size in bytes

`USE_DOCUMENT_SUMMARY`: Use document summary for contextual RAG

`USE_CHUNK_SUMMARY`: Use chunk summary for contextual RAG

  Most of the settings below can be configured in the admin UI.

:::

**General Connector Settings**

`ENABLED_CONNECTOR_TYPES`: Comma-separated list of enabled connector types

`LEAVE_CONNECTOR_ACTIVE_ON_INITIALIZATION_FAILURE`: Keep connector active on init failure

`CURATORS_CANNOT_VIEW_OR_EDIT_NON_OWNED_ASSISTANTS`: Restrict curator access

**Web Connector**

`WEB_CONNECTOR_VALIDATE_URLS`: Validate URLs in web connector

`HTML_BASED_CONNECTOR_TRANSFORM_LINKS_STRATEGY`: Link transformation strategy

`PARSE_WITH_TRAFILATURA`: Use Trafilatura for HTML parsing

**Confluence Connector**

`OAUTH_CONFLUENCE_CLOUD_CLIENT_ID`: Confluence Cloud OAuth client ID

`OAUTH_CONFLUENCE_CLOUD_CLIENT_SECRET`: Confluence Cloud OAuth client secret

`CONFLUENCE_CONNECTOR_LABELS_TO_SKIP`: Labels to skip during indexing

`CONFLUENCE_CONNECTOR_ATTACHMENT_SIZE_THRESHOLD`: Attachment size threshold

`CONFLUENCE_CONNECTOR_ATTACHMENT_CHAR_COUNT_THRESHOLD`: Attachment character threshold

`CONFLUENCE_CONNECTOR_USER_PROFILES_OVERRIDE`: User profiles override JSON

`CONFLUENCE_TIMEZONE_OFFSET`: Timezone offset for CQL queries

**Google Drive Connector**

`OAUTH_GOOGLE_DRIVE_CLIENT_ID`: Google Drive OAuth client ID

`OAUTH_GOOGLE_DRIVE_CLIENT_SECRET`: Google Drive OAuth client secret

`MAX_DRIVE_WORKERS`: Maximum Google Drive workers

`GOOGLE_DRIVE_CONNECTOR_SIZE_THRESHOLD`: File size threshold for Google Drive

**SharePoint Connector**

`SHAREPOINT_CONNECTOR_SIZE_THRESHOLD`: File size threshold for SharePoint

**Jira Connector**

`JIRA_CONNECTOR_LABELS_TO_SKIP`: Labels to skip during indexing

`JIRA_CONNECTOR_MAX_TICKET_SIZE`: Maximum ticket size in bytes

**GitHub Connector**

`GITHUB_CONNECTOR_BASE_URL`: GitHub base URL (for enterprise)

**GitLab Connector**

`GITLAB_CONNECTOR_INCLUDE_CODE_FILES`: Include code files in indexing

**Gong Connector**

`GONG_CONNECTOR_START_TIME`: Start time for Gong connector

**Notion Connector**

`NOTION_CONNECTOR_DISABLE_RECURSIVE_PAGE_LOOKUP`: Disable recursive page lookup

**Zendesk Connector**

`ZENDESK_CONNECTOR_SKIP_ARTICLE_LABELS`: Article labels to skip

**Egnyte Integration**

`EGNYTE_CLIENT_ID`: Egnyte OAuth client ID

`EGNYTE_CLIENT_SECRET`: Egnyte OAuth client secret

**Linear Integration**

`LINEAR_CLIENT_ID`: Linear OAuth client ID

`LINEAR_CLIENT_SECRET`: Linear OAuth client secret

`ALLOW_SIMULTANEOUS_PRUNING`: Allow simultaneous pruning operations

`MAX_PRUNING_DOCUMENT_RETRIEVAL_PER_MINUTE`: Maximum document retrieval rate during pruning

`OKTA_PROFILE_TOOL_ENABLED`: Enable Okta profile tool

`OKTA_API_TOKEN`: Okta API token for SSWS auth

`LOG_GIIS_MODEL_INTERACTIONS`: Log GiiS model interactions

`LOG_VESPA_TIMING_INFORMATION`: Log Vespa query performance

`LOG_ENDPOINT_LATENCY`: Log endpoint latency

`LOG_POSTGRES_LATENCY`: Log PostgreSQL latency

`LOG_POSTGRES_CONN_COUNTS`: Log PostgreSQL connection counts

`IMAGE_MODEL_NAME`: Image model name

`AZURE_IMAGE_API_VERSION`: Azure OpenAI image API version

`AZURE_IMAGE_API_KEY`: Azure OpenAI key used for image generation

`AZURE_IMAGE_API_BASE`: Azure OpenAI endpoint base URL for image generation

`AZURE_IMAGE_DEPLOYMENT_NAME`: Azure OpenAI image deployment namespace

`AZURE_DALLE_API_VERSION`: Legacy alias for `AZURE_IMAGE_API_VERSION` (kept for backwards compatibility)

`AZURE_DALLE_API_KEY`: Legacy alias for `AZURE_IMAGE_API_KEY` (kept for backwards compatibility)

`AZURE_DALLE_API_BASE`: Legacy alias for `AZURE_IMAGE_API_BASE` (kept for backwards compatibility)

`AZURE_DALLE_DEPLOYMENT_NAME`: Legacy alias for `AZURE_IMAGE_DEPLOYMENT_NAME` (kept for backwards compatibility)

`IMAGE_SUMMARIZATION_SYSTEM_PROMPT`: System prompt for image summarization

`IMAGE_SUMMARIZATION_USER_PROMPT`: User prompt for image summarization

`S3_FILE_STORE_BUCKET_NAME`: S3 bucket name for file storage

`S3_FILE_STORE_PREFIX`: S3 prefix for file storage

`S3_ENDPOINT_URL`: S3 endpoint URL (for MinIO and other S3-compatible storage)

`S3_VERIFY_SSL`: Verify SSL for S3 connections

`S3_AWS_ACCESS_KEY_ID`: AWS access key ID for S3

`S3_AWS_SECRET_ACCESS_KEY`: AWS secret access key for S3

`DISABLE_TELEMETRY`: Disable anonymous usage telemetry

`CUSTOM_ANSWER_VALIDITY_CONDITIONS`: Custom answer validity conditions

`API_PREFIX`: Used to prepend a base path for all API routes.
Set this to `/api` if you are running GiiS behind a reverse proxy that doesn't support stripping the `/api` prefix
from requests to the `API server`.

`API_KEY_HASH_ROUNDS`: Hash rounds for API keys

`LLM_MODEL_UPDATE_API_URL`: LLM model update API endpoint

`LITELLM_CUSTOM_ERROR_MESSAGE_MAPPINGS`: Custom error message mappings (JSON)

`GEN_AI_MODEL_FALLBACK_MAX_TOKENS`: Maximum token limit for generative AI model fallback

  [Contact us](/deployment/miscellaneous/contact_us) to enable Enterprise Edition features!

:::

`DATA_PLANE_SECRET`: Secret for secure control/data plane communication

`EXPECTED_API_KEY`: Additional security check for control plane API

`CONTROL_PLANE_API_BASE_URL`: Control plane API base URL

`DEV_MODE`: Enable development mode

`INTEGRATION_TESTS_MODE`: Enable integration tests mode

`MOCK_LLM_RESPONSE`: Boolean to create mock LLM responses for testing

`POD_NAME`: Kubernetes pod name

`POD_NAMESPACE`: Kubernetes pod namespace

`AWS_REGION_NAME`: AWS region name

`TARGET_AVAILABLE_TENANTS`: Number of pre-provisioned tenants to maintain

`SYSTEM_RECURSION_LIMIT`: System recursion limit

Enterprise Edition Environment Variables

Enterprise Edition adds additional environment variables to GiiS.

Setting this variable allows you to start your GiiS instance with pre-configured options that persist across
restarts.

`ENV_SEED_CONFIGURATION` accepts a JSON string with the following options:
- `llms`: List of LLM configurations (name, provider, api_key, api_base, api_version, custom_config, default_model_name, fast_default_model_name)
- `admin_user_emails`: List of email addresses for automatic admin role assignment
- `seeded_name`: Pre-set name for your GiiS instance
- `seeded_logo_path`: Path to your logo within the assets folder

This variable allows you to configure the number of rounds used in the SHA-256 Crypt hashing algorithm for API keys.
- Default value: `535000`
- Allowed range: `1000` to `999999999`

  Increasing this value enhances security but may impact performance.
  The default value provides a good balance for most use cases.

:::