Skip to main content

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.

VariableDescriptionRequiredDefault Value
DB_HOSTThe database hosttrue
DB_PORTThe port used to connect to the databasetrue
DB_NAMEThe name of the databasetrue
DB_USERThe username that will be used to connect to the databasetrue
DB_PASSThe password that will be used by the DB_USER to connect to the databasetrue
DB_SSL_DISABLEPostgres requires SSL by default. Set this to "true" to disable SSL, which is useful for dev environmentsfalsefalse
DB_AUTO_MIGRATEIf true, will automatically run the database migrations prior to startup. Only loaded if DB_AUTO_MIGRATE is set to "true"falsefalse
DB_SCHEMA_DIRThe directory where the migrations scripts are found.false
DB_OPTIONSSets the "options" query parameter in the postgres urlfalse
HOSTThe host that will be used when binding the HTTP server. Set this to "0.0.0.0" for production environmentsfalse127.0.0.1
PORTThe port that will be used to bind the HTTP serverfalse8080
NUCLEUS_ENVThe environment that is being deployed to. Useful for metricsfalseunknown
SHUTDOWN_TIMEOUT_SECONDSConfigures the graceful shutdown of a pod in Kubernetesfalse
LOGS_FORMAT_JSONWhether or not to format logs in JSON or in plaintext to stdoutfalsetrue
AUTH_ENABLEDWhether or not to enable authentication in the API. Should be required for any production environmentfalsefalse
AUTH_BASEURLThe base URL for the authentication server. This is used to find the JWKS URL to validate JWT tokensfalse
AUTH_EXPECTED_ISSThe 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_AUDIENCEThe audience that is to be used for validating JWT tokens. Can pass multiple values using a comma separatortruefalse
AUTH_CLIENTID_SECRETThis is a JSON stringified map of clientId:secret used to validate authentication requests for JWT tokensfalse
AUTH_CLI_AUDIENCEUsed to validate which audience the CLI is to use to make requests to the API serverfalse
AUTH_SIGNATURE_ALGORITHMExpected algorithm the JWT will have been encoded with.false
TEMPORAL_URLThe URL used to connect to the temporal instancefalseRS256
TEMPORAL_CERT_KEY_PATHThe path where the API can find the mTLS certificate key to authenticate against Temporalfalse
TEMPORAL_CERT_PATHThe path where the API can find the mTLS certificate to authenticate against Temporalfalse
TEMPORAL_CERTThe Temporal mTLS certificate contentsfalse
TEMPORAL_CERT_KEYThe Temporal mTLS certificate key contentsfalse
TEMPORAL_DEFAULT_NAMESPACEThe default temporal namespace used for any new accountfalsedefault
TEMPORAL_DEFAULT_SYNCJOB_QUEUEThe default Temporal queue name for Neosync jobsfalsesync-job
AUTH_API_CLIENT_IDThe client id that the API uses to connect to the auth provider's admin/management API to retrieve user datafalse
AUTH_API_CLIENT_SECRETThe client secret that the API uses to connect to the auth provider's admin/management API to retrieve user datafalse
AUTH_API_PROVIDERThe name of the provider that will be used to determine which SDK to use. Accepted values are: auth0, keycloakfalse
AUTH_API_BASEURLThe base URL of the Admin APIfalse
KUBERNETES_ENABLEDWhether or not API is running in Kubernetes. Used to enable kubernetes specific featuresfalsefalse
KUBERNETES_NAMESPACEKubernetes namespace that API is running infalse
KUBERNETES_WORKER_APP_NAMEApp name of Worker running in Kubernetesfalse
METRICS_SERVICE_ENABLEDWhether or not to enable the metrics gRPC servicefalsefalse
METRICS_URLIf the metrics service is enabled, this points it to the underlying prometheus instancefalsehttp://localhost:9090
METRICS_API_KEYIf the $METRICS_URL requires authentication, this will be passed to the apifalse
DB_LOG_LEVELEnables 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.falseNONE
LOG_LEVELDetermines the level of logging that will be visible out of the backend logger.falseINFO
RUN_LOGS_ENABLEDDetermines if run logs should be enabledfalsefalse
RUN_LOGS_TYPEDetermines which type of run logs should be enabled. Required if RUN_LOGS_ENABLED=true. Values: k8s-pods, lokifalse
RUN_LOGS_PODCONFIG_WORKER_NAMESPACEThe namespace that neosync-worker is running in. Only used if RUN_LOGS_TYPE=k8s-podsfalse$KUBERNETES_NAMESPACE
RUN_LOGS_PODCONFIG_WORKER_APPNAMEThe app name of the worker that is used during the label selection. Only used if RUN_LOGS_TYPE=k8s-podsfalse$KUBERNETES_WORKER_APP_NAME or neosync-worker
RUN_LOGS_LOKICONFIG_BASEURLThe baseurl for the running loki gateway. Only used if RUN_LOGS_TYPE=lokifalse
RUN_LOGS_LOKICONFIG_LABELSQUERYThe 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=lokifalsenamespace="neosync", app="neosync-worker"
RUN_LOGS_LOKICONFIG_KEEPLABELSWhether or not to keep the labels in the response. Only used if RUN_LOGS_TYPE=lokifalsefalse
OTEL_SDK_DISABLEDWhether or not to disable OpenTelemetryfalsefalse
OTEL_SERVICE_VERSIONThe version of the service that will be used with for reportingfalse
OTEL_TRACES_EXPORTERThe exporter that will be used. Allowed: otlp, console, none. If otlp, uses grpc.falseotlp
OTEL_METRICS_EXPORTERThe exporter that will be used. Allowed: otlp, console, none. If otlp, uses grpcfalseotlp
MAX_ALLOWED_RECORDSThe max allowed records that are allowed for an account to ingest (currently only applies to Personal accounts in Neosync Cloud)falseNULL

Backend API Database Migrations

These environment variables are loaded when running the mgmt migrate up command which runs database migrations.

VariableDescriptionRequiredDefault Value
DB_HOSTThe database hosttrue
DB_PORTThe port used to connect to the databasetrue
DB_NAMEThe name of the databasetrue
DB_USERThe username that will be used to connect to the databasetrue
DB_PASSThe password that will be used by the DB_USER to connect to the databasetrue
DB_SSL_DISABLEPostgres requires SSL by default. Set this to "true" to disable SSL, which is useful for dev environmentsfalsefalse
DB_SCHEMA_DIRThe directory where the migrations scripts are found.false
DB_MIGRATIONS_TABLEThe name of the table where the migrations will be tracked. Useful if you want to override the default, or put into a different schemafalse
DB_MIGRATIONS_TABLE_QUOTEDIf the table set in DB_MIGRATIONS_TABLE contains quotesfalse
DB_MIGRATIONS_OPTIONSSets 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_URLThe full postgres url. Overrides all of the above variables that are used to construct the urlfalse

Frontend App

VariableDescriptionIs RequiredDefault Value
AUTH_ENABLEDWhether or not to enable authentication in the App. Should be required for any production environmentfalsefalse
NEXTAUTH_URLThis 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 truefalse
NEXTAUTH_SECRETThis 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_IDThe client id that will be used to authenticate via the configured auth provider. Required if AUTH_ENABLED is truefalse
AUTH_CLIENT_SECRETThe client secret that will be used to authenticate via the configured auth provider. Required if AUTH_ENABLED is truefalse
AUTH_ISSUERThe issuer url. This is typically the baseurl for the auth instance. Required if AUTH_ENABLED is truefalse
AUTH_EXPECTED_ISSUERThe 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 urlfalse
AUTH_SCOPEThe space separated list of scopes that will be requested when issuing an access token. Required if AUTH_ENABLED is truefalse
AUTH_AUDIENCEThe audience that will be used when requesting the access token. Required if AUTH_ENABLED is true truefalse
AUTH_PROVIDER_IDThe 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_NAMEThe 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_URLThe 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_URLThe base url of the Neosync API. This can be overridden to connect to different Neosync API environmentsfalsehttp://localhost:8080
AUTH_AUTHORIZE_URLThe 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_URLThe 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_URLThe 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_HOSTWhether 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_ENABLEDEnables analytics within the Neosync app. Disable to turn off all analytics.falsetrue
POSTHOG_KEYAPI key used to send analytics to Posthog. Without this, analytics will be disabled, even if NEOSYNC_ANALYTICS_ENABLED is set to true.falseNeosync's posthog api key
POSTHOG_HOSTUsed 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.falsehttps://app.posthog.com
ENABLE_RUN_LOGSUsed to enable job run logs on job run page. Worker and API must be running in Kubernetesfalsefalse
METRICS_SERVICE_ENABLEDWhether or not to enable displaying metrics. This may only be enabled if the backend also has the metrics service configuredfalsefalse

Worker

These environment variables are loaded when running the worker serve command which starts the main worker instance.

VariableDescriptionIs RequiredDefault Value
HOSTThe host that will be used when binding the http server. Set this to "0.0.0.0" for production environmentsfalse127.0.0.1
PORTThe port that will be used to bind the http serverfalse8080
TEMPORAL_URLThe url used to connect to the temporal instancefalselocalhost:7233
TEMPORAL_NAMESPACEThe Temporal namespace to connect tofalsedefault
TEMPORAL_TASK_QUEUEThe Temporal task queue name to connect to for Neosync jobstrue
TEMPORAL_CERT_KEY_PATHThe 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 variablefalse
TEMPORAL_CERT_PATHThe 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 variablefalse
TEMPORAL_CERTThe Temporal mTLS certificate contents. Use this if you want to load contents directly instead of mounting them to the filesystemfalse
TEMPORAL_CERT_KEYThe Temporal mTLS certificate key contents. Use this if you want to load the contents directly instead of mounting them to the filesystemfalse
NEOSYNC_URLThe base url of the Neosync API that the worker will use to connect tofalselocalhost:8080
REDIS_URLThe url of the redis serverfalse
REDIS_KINDSpecifies which redis client to use. Options are simple, cluster or failoverfalse
REDIS_MASTERName of redis master when redis kind is failoverfalse
REDIS_TLS_ENABLEDWhether to enable TLSfalse
REDIS_TLS_SKIP_CERT_VERIFYWhether to skip server side certificate verificationfalse
REDIS_TLS_ENABLE_RENEGOTIATIONWhether to allow the remote server to repeatedly request renegotiationfalse
REDIS_TLS_ROOT_CERT_AUTHORITYRoot certificate authority to usefalse
REDIS_TLS_ROOT_CERT_AUTHORITY_FILEPath of root certificate authority file to usefalse
DB_LOG_LEVELEnables 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.falseNONE
LOG_LEVELDetermines the level of logging that will be visible out of the worker logger.falseINFO
OTEL_SDK_DISABLEDWhether or not to disable OpenTelemetryfalsefalse
OTEL_SERVICE_VERSIONThe version of the service that will be used with for reportingfalse
OTEL_TRACES_EXPORTERThe exporter that will be used. Allowed: otlp, console, none. If otlp, uses grpc.falseotlp
OTEL_METRICS_EXPORTERThe exporter that will be used. Allowed: otlp, console, none. If otlp, uses grpcfalseotlp
CHECK_ACCOUNT_TIMER_SECONDSAn integer in seconds for how frequently the account status should be verifiedfalse5

CLI

There are some environment variables that the CLI accepts to override default behavior to accommodate different environments.

VariableDescriptionIs RequiredDefault Value
NEOSYNC_API_URLThe base url of the Neosync API. This can be overridden to connect to different Neosync API environmentsfalsehttp://localhost:8080
NEOSYNC_API_KEYThe api key for Neosync API.false
LOGIN_HOSTThe http server that is booted up running neosync login via an oauth flowfalse127.0.0.1
LOGIN_REDIRECT_HOSTThe redirect host that is sent alongside the oauth flow when running neosync loginfalse127.0.0.1
LOGIN_PORTThe port the http server runs on when running neosync loginfalse4242
NEOSYNC_CONFIG_DIRThe 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