Environment Variables
Overview
The purpose of this page is to list in detail each of the environment variables that are required to launch neosync services. There are three discrete services in Neosync, and each one has its own purpose. See the Platform Overview section of the docs to understand more about the makeup of Neosync.
Backend API
These environment variables are loaded when running the mgmt serve connect command which starts the main API instance.
| Variable | Description | Required | Default Value |
|---|---|---|---|
| DB_HOST | The database host | true | |
| DB_PORT | The port used to connect to the database | true | |
| DB_NAME | The name of the database | true | |
| DB_USER | The username that will be used to connect to the database | true | |
| DB_PASS | The password that will be used by the DB_USER to connect to the database | true | |
| DB_SSL_DISABLE | Postgres requires SSL by default. Set this to "true" to disable SSL, which is useful for dev environments | false | false |
| DB_AUTO_MIGRATE | If true, will automatically run the database migrations prior to startup. Only loaded if DB_AUTO_MIGRATE is set to "true" | false | false |
| DB_SCHEMA_DIR | The directory where the migrations scripts are found. | false | |
| DB_OPTIONS | Sets the "options" query parameter in the postgres url | false | |
| HOST | The host that will be used when binding the HTTP server. Set this to "0.0.0.0" for production environments | false | 127.0.0.1 |
| PORT | The port that will be used to bind the HTTP server | false | 8080 |
| NUCLEUS_ENV | The environment that is being deployed to. Useful for metrics | false | unknown |
| SHUTDOWN_TIMEOUT_SECONDS | Configures the graceful shutdown of a pod in Kubernetes | false | |
| LOGS_FORMAT_JSON | Whether or not to format logs in JSON or in plaintext to stdout | false | true |
| AUTH_ENABLED | Whether or not to enable authentication in the API. Should be required for any production environment | false | false |
| AUTH_BASEURL | The base URL for the authentication server. This is used to find the JWKS URL to validate JWT tokens | false | |
| AUTH_EXPECTED_ISS | The public base url for the authentication server. This is used to validate incoming JWT token "iss" claims. Only needed if the backend communicates internally with the auth server. | false | |
| AUTH_AUDIENCE | The audience that is to be used for validating JWT tokens. Can pass multiple values using a comma separator | true | false |
| AUTH_CLIENTID_SECRET | This is a JSON stringified map of clientId:secret used to validate authentication requests for JWT tokens | false | |
| AUTH_CLI_AUDIENCE | Used to validate which audience the CLI is to use to make requests to the API server | false | |
| AUTH_SIGNATURE_ALGORITHM | Expected algorithm the JWT will have been encoded with. | false | |
| TEMPORAL_URL | The URL used to connect to the temporal instance | false | RS256 |
| TEMPORAL_CERT_KEY_PATH | The path where the API can find the mTLS certificate key to authenticate against Temporal | false | |
| TEMPORAL_CERT_PATH | The path where the API can find the mTLS certificate to authenticate against Temporal | false | |
| TEMPORAL_CERT | The Temporal mTLS certificate contents | false | |
| TEMPORAL_CERT_KEY | The Temporal mTLS certificate key contents | false | |
| TEMPORAL_DEFAULT_NAMESPACE | The default temporal namespace used for any new account | false | default |
| TEMPORAL_DEFAULT_SYNCJOB_QUEUE | The default Temporal queue name for Neosync jobs | false | sync-job |
| AUTH_API_CLIENT_ID | The client id that the API uses to connect to the auth provider's admin/management API to retrieve user data | false | |
| AUTH_API_CLIENT_SECRET | The client secret that the API uses to connect to the auth provider's admin/management API to retrieve user data | false | |
| AUTH_API_PROVIDER | The name of the provider that will be used to determine which SDK to use. Accepted values are: auth0, keycloak | false | |
| AUTH_API_BASEURL | The base URL of the Admin API | false | |
| KUBERNETES_ENABLED | Whether or not API is running in Kubernetes. Used to enable kubernetes specific features | false | false |
| KUBERNETES_NAMESPACE | Kubernetes namespace that API is running in | false | |
| KUBERNETES_WORKER_APP_NAME | App name of Worker running in Kubernetes | false | |
| METRICS_SERVICE_ENABLED | Whether or not to enable the metrics gRPC service | false | false |
| METRICS_URL | If the metrics service is enabled, this points it to the underlying prometheus instance | false | http://localhost:9090 |
| METRICS_API_KEY | If the $METRICS_URL requires authentication, this will be passed to the api | false | |
| DB_LOG_LEVEL | Enables database query logging for postgres databases. This will also enable DB logging for traffic to the Neosync database. Note that if the $LOG_LEVEL is set to ERROR and $DB_LOG_LEVEL is set to INFO, you will only see ERROR level logs for the database as it uses the underlying logger. | false | NONE |
| LOG_LEVEL | Determines the level of logging that will be visible out of the backend logger. | false | INFO |
| RUN_LOGS_ENABLED | Determines if run logs should be enabled | false | false |
| RUN_LOGS_TYPE | Determines which type of run logs should be enabled. Required if RUN_LOGS_ENABLED=true. Values: k8s-pods, loki | false | |
| RUN_LOGS_PODCONFIG_WORKER_NAMESPACE | The namespace that neosync-worker is running in. Only used if RUN_LOGS_TYPE=k8s-pods | false | $KUBERNETES_NAMESPACE |
| RUN_LOGS_PODCONFIG_WORKER_APPNAME | The app name of the worker that is used during the label selection. Only used if RUN_LOGS_TYPE=k8s-pods | false | $KUBERNETES_WORKER_APP_NAME or neosync-worker |
| RUN_LOGS_LOKICONFIG_BASEURL | The baseurl for the running loki gateway. Only used if RUN_LOGS_TYPE=loki | false | |
| RUN_LOGS_LOKICONFIG_LABELSQUERY | The base labels query that is used to select the logs. More labels are attached based on the active request. Only used if RUN_LOGS_TYPE=loki | false | namespace="neosync", app="neosync-worker" |
| RUN_LOGS_LOKICONFIG_KEEPLABELS | Whether or not to keep the labels in the response. Only used if RUN_LOGS_TYPE=loki | false | false |
| OTEL_SDK_DISABLED | Whether or not to disable OpenTelemetry | false | false |
| OTEL_SERVICE_VERSION | The version of the service that will be used with for reporting | false | |
| OTEL_TRACES_EXPORTER | The exporter that will be used. Allowed: otlp, console, none. If otlp, uses grpc. | false | otlp |
| OTEL_METRICS_EXPORTER | The exporter that will be used. Allowed: otlp, console, none. If otlp, uses grpc | false | otlp |
| MAX_ALLOWED_RECORDS | The max allowed records that are allowed for an account to ingest (currently only applies to Personal accounts in Neosync Cloud) | false | NULL |
Backend API Database Migrations
These environment variables are loaded when running the mgmt migrate up command which runs database migrations.
| Variable | Description | Required | Default Value |
|---|---|---|---|
| DB_HOST | The database host | true | |
| DB_PORT | The port used to connect to the database | true | |
| DB_NAME | The name of the database | true | |
| DB_USER | The username that will be used to connect to the database | true | |
| DB_PASS | The password that will be used by the DB_USER to connect to the database | true | |
| DB_SSL_DISABLE | Postgres requires SSL by default. Set this to "true" to disable SSL, which is useful for dev environments | false | false |
| DB_SCHEMA_DIR | The directory where the migrations scripts are found. | false | |
| DB_MIGRATIONS_TABLE | The name of the table where the migrations will be tracked. Useful if you want to override the default, or put into a different schema | false | |
| DB_MIGRATIONS_TABLE_QUOTED | If the table set in DB_MIGRATIONS_TABLE contains quotes | false | |
| DB_MIGRATIONS_OPTIONS | Sets the "options" query parameter in the postgres url. Note the DB_OPTIONS is only used for the API to connect. This is a separate options explicitly used for the migration scripts. | false | |
| DB_URL | The full postgres url. Overrides all of the above variables that are used to construct the url | false |
Frontend App
| Variable | Description | Is Required | Default Value |
|---|---|---|---|
| AUTH_ENABLED | Whether or not to enable authentication in the App. Should be required for any production environment | false | false |
| NEXTAUTH_URL | This the base url that the app will be accessible from. Note: this is not the base url for the auth service, but for the app itself. Required if AUTH_ENABLED is true | false | |
| NEXTAUTH_SECRET | This is a secret value that is used to encrypt the next-auth cookie that is stored in the browser. This should change per environment. | true | |
| AUTH_CLIENT_ID | The client id that will be used to authenticate via the configured auth provider. Required if AUTH_ENABLED is true | false | |
| AUTH_CLIENT_SECRET | The client secret that will be used to authenticate via the configured auth provider. Required if AUTH_ENABLED is true | false | |
| AUTH_ISSUER | The issuer url. This is typically the baseurl for the auth instance. Required if AUTH_ENABLED is true | false | |
| AUTH_EXPECTED_ISSUER | The frontend issuer url. This is typically used if the auth service is accessed behind a proxy, or if the backend uses an internal url to access the auth service, but the client needs a different, public url. Common in networked or docker environments where the backend uses a cluster-local dns entry, while the client needs a public url | false | |
| AUTH_SCOPE | The space separated list of scopes that will be requested when issuing an access token. Required if AUTH_ENABLED is true | false | |
| AUTH_AUDIENCE | The audience that will be used when requesting the access token. Required if AUTH_ENABLED is true true | false | |
| AUTH_PROVIDER_ID | The id of your provider. This is used by next-auth to identify the provider. This can really be anything you want. Required if AUTH_ENABLED is true. | false | |
| AUTH_PROVIDER_NAME | The name of your provider. This is used on the next-auth signin page and appears in the button text that a user will select. Required if AUTH_ENABLED is true. | false | |
| NEXT_PUBLIC_APP_BASE_URL | The url of the app. This is typically the same as NEXTAUTH_URL. Used for generating invite urls, among other things. This is not baked into the HTML or the image. | false | |
| NEOSYNC_API_BASE_URL | The base url of the Neosync API. This can be overridden to connect to different Neosync API environments | false | http://localhost:8080 |
| AUTH_AUTHORIZE_URL | The full url that routes to the authorize url. This is optional and may be necessary if you're using AUTH_EXPECTED_ISSUER as the urls will be different. This will need to include the public url (same value as AUTH_EXPECTED_ISSUER). If using a fully external auth provider, this will most likely not be needed. | false | |
| AUTH_USERINFO_URL | The full url that routes to the userinfo url. This is optional and may be necessary if you're using AUTH_EXPECTED_ISSUER as the urls will be different. This will most likely need to include the internal url (same value as AUTH_ISSUER). If using a fully external auth provider, this will most likely not be needed. | false | |
| AUTH_TOKEN_URL | The full url that routes to the token url. This is optional and may be necessary if you're using AUTH_EXPECTED_ISSUER as the urls will be different. This will most likely need to include the internal url (same value as AUTH_ISSUER). If using a fully external auth provider, this will most likely not be needed. | false | |
| AUTH_TRUST_HOST | Whether or not to trust the external host. Check the next-auth docs for more details. This is pretty must required if running behind a load balancer. | true | |
| NEOSYNC_ANALYTICS_ENABLED | Enables analytics within the Neosync app. Disable to turn off all analytics. | false | true |
| POSTHOG_KEY | API key used to send analytics to Posthog. Without this, analytics will be disabled, even if NEOSYNC_ANALYTICS_ENABLED is set to true. | false | Neosync's posthog api key |
| POSTHOG_HOST | Used to change the host of the Posthog instance that analytics are shipped to. Only needed if self-hosting Posthog or not shipping to the default Posthog platform. | false | https://app.posthog.com |
| ENABLE_RUN_LOGS | Used to enable job run logs on job run page. Worker and API must be running in Kubernetes | false | false |
| METRICS_SERVICE_ENABLED | Whether or not to enable displaying metrics. This may only be enabled if the backend also has the metrics service configured | false | false |
Worker
These environment variables are loaded when running the worker serve command which starts the main worker instance.
| Variable | Description | Is Required | Default Value |
|---|---|---|---|
| HOST | The host that will be used when binding the http server. Set this to "0.0.0.0" for production environments | false | 127.0.0.1 |
| PORT | The port that will be used to bind the http server | false | 8080 |
| TEMPORAL_URL | The url used to connect to the temporal instance | false | localhost:7233 |
| TEMPORAL_NAMESPACE | The Temporal namespace to connect to | false | default |
| TEMPORAL_TASK_QUEUE | The Temporal task queue name to connect to for Neosync jobs | true | |
| TEMPORAL_CERT_KEY_PATH | The path on the filesystem where the worker can find the mTLS certificate key it will use to authenticate against Temporal. This will be used over the TEMPORAL_CERT_KEY environment variable | false | |
| TEMPORAL_CERT_PATH | The path on the filesystem where the worker can find the mTLS certificate that will be used to authenticate against Temporal. This will be used over the TEMPORAL_CERT environment variable | false | |
| TEMPORAL_CERT | The Temporal mTLS certificate contents. Use this if you want to load contents directly instead of mounting them to the filesystem | false | |
| TEMPORAL_CERT_KEY | The Temporal mTLS certificate key contents. Use this if you want to load the contents directly instead of mounting them to the filesystem | false | |
| NEOSYNC_URL | The base url of the Neosync API that the worker will use to connect to | false | localhost:8080 |
| REDIS_URL | The url of the redis server | false | |
| REDIS_KIND | Specifies which redis client to use. Options are simple, cluster or failover | false | |
| REDIS_MASTER | Name of redis master when redis kind is failover | false | |
| REDIS_TLS_ENABLED | Whether to enable TLS | false | |
| REDIS_TLS_SKIP_CERT_VERIFY | Whether to skip server side certificate verification | false | |
| REDIS_TLS_ENABLE_RENEGOTIATION | Whether to allow the remote server to repeatedly request renegotiation | false | |
| REDIS_TLS_ROOT_CERT_AUTHORITY | Root certificate authority to use | false | |
| REDIS_TLS_ROOT_CERT_AUTHORITY_FILE | Path of root certificate authority file to use | false | |
| DB_LOG_LEVEL | Enables database query logging for postgres databases. Note that if the $LOG_LEVEL is set to ERROR and $DB_LOG_LEVEL is set to INFO, you will only see ERROR level logs for the database as it uses the underlying logger. | false | NONE |
| LOG_LEVEL | Determines the level of logging that will be visible out of the worker logger. | false | INFO |
| OTEL_SDK_DISABLED | Whether or not to disable OpenTelemetry | false | false |
| OTEL_SERVICE_VERSION | The version of the service that will be used with for reporting | false | |
| OTEL_TRACES_EXPORTER | The exporter that will be used. Allowed: otlp, console, none. If otlp, uses grpc. | false | otlp |
| OTEL_METRICS_EXPORTER | The exporter that will be used. Allowed: otlp, console, none. If otlp, uses grpc | false | otlp |
| CHECK_ACCOUNT_TIMER_SECONDS | An integer in seconds for how frequently the account status should be verified | false | 5 |
CLI
There are some environment variables that the CLI accepts to override default behavior to accommodate different environments.
| Variable | Description | Is Required | Default Value |
|---|---|---|---|
| NEOSYNC_API_URL | The base url of the Neosync API. This can be overridden to connect to different Neosync API environments | false | http://localhost:8080 |
| NEOSYNC_API_KEY | The api key for Neosync API. | false | |
| LOGIN_HOST | The http server that is booted up running neosync login via an oauth flow | false | 127.0.0.1 |
| LOGIN_REDIRECT_HOST | The redirect host that is sent alongside the oauth flow when running neosync login | false | 127.0.0.1 |
| LOGIN_PORT | The port the http server runs on when running neosync login | false | 4242 |
| NEOSYNC_CONFIG_DIR | The config directory to store Neosync-specific credentials. For Linux users, $XDG_CONFIG_HOME is also respected. | false | ~/.neosync |
Open Telemetry
Neosync has support for Opentelemetry Tracing and Metering.
View the compliance matrix to see what values are understood directly via the Go SDK.
Any OTEL_ environment variables that are documented in the table(s) above are directly used by the Neosync services and drive the configuration of the OTEL SDK.
Anything not documented in those tables and is supported vai the compliance matrix should be configurable simply by setting the environment variables (ex: OTEL_EXPORTER_OTLP_ENDPOINT)
Otel SDK Environment Variable Reference Otel SDK Environment Variable Compliance Matrix