Environment Variables

The Hoss uses and environment variables file to maintain some common and sensitive information. These data are used to configure various parts of the system, and in the future in more advanced deployment scenarios could be moved to other secure means of managing environment variables.

The file where env vars are stored is located at ~/.hoss/.env.

This file is pre-populated with default values configured for local development & testing via the make env command. By default:

  • System runs on localhost

  • No TLS

  • All services are run

  • Internal auth is enabled with default accounts

Note, the make config command uses data in the .env file, so you must complete any desired changes to the environment variables before running make config.

Warning

If the .env file is deleted after a server has been started (e.g. by running make reset) you will lose access to the database, rabbitmq, and internal ldap server due to credentials being store in this file.

Variables

SERVICES

Default: opensearch ldap rabbitmq db dex reverse-proxy auth ldap-admin etcd-0 minio core ui sync

This variable is a string with service names to deploy separated by spaces. The service name maps to the names in the the associated Docker Compose file.

To disable minIO (i.e. you are using S3), remove minio, etcd-0, and rabbitmq.

To disable auth (i.e. you are using another server’s auth service in a hybrid cloud configuration), remove ldap, dex, auth, and ldap-admin.

To disable sync (i.e. you are running the sync service in another server), remove sync.

HOSS_DIR

Default: <your user directory>/.hoss

This is the location of the Hoss working directory.

LETS_ENCRYPT_ENABLED

Default: false

If True, Let’s Encrypt will be used to provision a TLS certificate. TLS termination will then be done at the ingress proxy of the server. Your EXTERNAL_HOSTNAME must start with https in this case. You must also set the ADMIN_EMAIL variable.

Note

If enabled, the server must be accessible on port 80 for the ACME challenge to succeed. All traffic (besides the challenge) is automatically redirected to 443, so you are still able to lock down the server at the network level if desired.

EXTERNAL_HOSTNAME

Default: http://localhost

The external hostname of the server, including the protocol. If TLS is enabled, either via Let’s Encrypt or externally via something like an AWS ALB, the hostname must start with https. There should be no trailing slash.

DOMAIN

Default: localhost

The domain of the server (i.e. EXTERNAL_HOSTNAME without the http/https).

AUTH_SERVICE_ENDPOINT

Default: http://auth:8080/v1

The endpoint used by other services to contact the auth service. If you are running the auth service (i.e. it is in the SERVICES variable) then you can use the default internal route.

If you are using another server’s auth service (e.g. in a hybrid cloud configuration), this should be set to that server’s external route to the auth service (e.g. https://my-hoss-server.mycompany.com/auth/v1). There should be no trailing slash.

HEALTH_CHECK_HOST

Default: Empty

If set, an additional route to the “core” service for this host will be added to the ingress proxy for external health checks. This is needed when deployed behind things like an AWS Application Load Balancer. The ALB will run health checks using the internal IP address, which by default won’t match any routes. If you provide this internal IP address, then an additional route will be added and the server will appear healthy.

For example, if the internal IP of the server is 10.0.1.100 you would set HEALTH_CHECK_HOST=10.0.1.100.

ADMIN_EMAIL

Default: Empty

If LETS_ENCRYPT_ENABLED=true this variable is required. Set it to an email address that will be provided to Let’s Encrypt for certificate expiration notices.

NAS_ROOT

Default: ~/.hoss/data/nas

The location of the folder that will serve as the root for minIO in gateway mode (if enabled). To create a bucket, create a folder with the name of the bucket in this location.

MINIO_ROOT_USER

Default: root

Minio root user name.

MINIO_ROOT_PASSWORD

Default: <auto-generated-random-value>

The password for the root minIO account. This is automatically generated when make env is run.

DB_ROOT

Default: ~/.hoss/data/db

The location of the folder that will contain the database. There is typically no need to change this value.

POSTGRES_USER

Default: postgres

The PostgreSQL database username that the system will use to connect to the database. There is typically no need to change this value.

POSTGRES_PASSWORD

Default: <auto-generated-random-value>

The password for the POSTGRES_USER to access the database. This is automatically generated when make env is run.

DB_INIT_SCRIPTS

Default: /Users/dean/.hoss/core/db-init-scripts

This location will be mounted into the database container and contains all the database init scripts. For example, when a restore is happening, additional files may be put here before the database is started. There is typically no need to change this value.

POSTGRES_CORE_DB

Default: hoss_core

The name of the database used by the core service. There is typically no need to change this value.

POSTGRES_AUTH_DB

Default: hoss_auth

The name of the database used by the auth service. There is typically no need to change this value.

RABBITMQ_USER

Default: gigantum

The name of the user when connecting to rabbitmq. There is typically no need to change this value.

RABBITMQ_PASS

Default: <auto-generated-random-value>

The password for RABBITMQ_USER when connecting to rabbitmq. It is automaticaly generated when make env is run.

SERVICE_AUTH_SECRET

Default: hsvc_<auto-generated-random-value>

The service account access token that will be used when the service account is making API requests. It is automaticaly generated when make env is run.

LDAP_ADMIN_PASSWORD

Default: <auto-generated-random-value>

The password for the LDAP admin account (not to be confused with the test Hoss user administrator account). You use this password to connect to the LDAP server as an administrator to edit user accounts.

LDAP_READONLY_PASSWORD

Default: <auto-generated-random-value>

Password used by Dex to bind to the LDAP server and authenticate users. Connects with read-only access.

LDAP_ORGANISATION

Default: Gigantum Inc.

Organization for the integrated LDAP server (if enabled).

LDAP_DOMAIN

Default: hoss.gigantum.com

Root domain for the integrated LDAP server (if enabled).

UID

Default: <auto-generated>

This is the host UID of the user who runs make env. This value is used to set permissions on files in containers to the user who is starting the system.

GID

Default: <auto-generated>

This is the host GID of the user who runs make env. This value is used to set permissions on files in containers to the user who is starting the system.

BACKUP_ROOT

Default: ~/.hoss/backup

This is the backup location for the system. The directory will contain bind mounts to various containers to support the backup/restore process, along with any final backup archive.

RECAPTCHA_SITE_KEY

Default: Blank

Set this optional field with a valid reCaptcha site key and then run make config to activate a reCaptcha widget on the log in page. This is only supported when using the internal LDAP auth provider.

RECAPTCHA_SECRET_KEY

Default: Blank

Set this optional field with a valid reCaptcha secret key and then run make config to activate a reCaptcha widget on the log in page. This is only supported when using the internal LDAP auth provider.

UI_REDIRECT_REGEX

Default: <auto-generated>

This variable is set based on the DOMAIN value when make config is run. It is a regular expression that is used to match on requests to the root of the server and redirect them to the UI service (/ui). For example, if DOMAIN was set to hoss.myserver.com, UI_REDIRECT_REGEX would automatically be set to https?://hoss\.myserver\.com/ .

You should not have to manually change this from the auto-generated value if you have properly set your DOMAIN value.