Skip to main content

Environment Configuration

To get Tombolo up and running, you'll need to configure two essential files. For your convenience, sample .env files are already included in the project. Simply copy these sample files and adjust the values to suit your specific environment.

  1. General Environment File:
    This file contains server-related configurations and Docker-related settings. It is located in the root directory of the project: Tombolo/Tombolo/.env.

  2. Client-Specific Environment File:
    This file is specific to the client-side application and is located in Tombolo/Tombolo/client-reactjs/.env.

Important: Review and understand the variables in these files as they may differ depending on your environment. Detailed explanations for each variable are provided below.


Server Environment Variables​

Below are the server and Docker-related configuration variables for Tombolo. These variables are also referenced in the Docker Compose file. Each one is explained with its purpose and usage.

1. Instance Configuration​

  • INSTANCE_NAME
    This variable is used to give a unique name to the instance of the Tombolo application.
    Example: tombolo_dev_1

  • NODE_ENV
    Defines the environment type in which Tombolo will run. It can either be set to development or production.
    Example: development

  • NODE_LOG_LEVEL
    The logging level for the Node.js server. Options include error, warn, info, http, verbose, debug, and silly. For more information on configuring logging with Winston, refer to the Winston Configuration.
    Example: http

2. Host, Port, and Web URL Configuration​

  • HOSTNAME
    This defines the hostname that Tombolo will use. Typically, localhost is used for local development, but in a production setup, this could be a domain name or an IP address where the Tombolo server is hosted.
    Example: localhost

  • SERVER_PORT
    Specifies the port on which the backend server will run. This is the port that handles API requests and communications between the frontend and backend.
    Example: 3001

  • HTTP_PORT
    This port is dedicated to the frontend interface of Tombolo. When running locally, the frontend will be accessible through this port.
    Example: 3000

  • HTTPS_PORT
    Port used for secure HTTP traffic (HTTPS). If SSL/TLS isn't configured or required for your local setup, this setting can be ignored.
    Example: 443

  • WEB_URL
    URL to access Tombolo's web interface. It is composed of the hostname and HTTP port. In production, this would be a FQDN.
    Example: http://localhost:3000/

3. SSL Certificate Configuration (Nginx)​

These configurations are required if you're using SSL/TLS. Ignore if not using SSL.

  • CERT_PATH
    Specifies the directory path where SSL certificates are stored. This path is referenced by Nginx.
    Example: /certs

  • CERTIFICATE_NAME
    The file name of your SSL certificate.
    Example: my_certificate.pem

  • CERTIFICATE_KEY
    The file name of the SSL certificate's private key.
    Example: my_certificate_key.pem

4. Database Configuration​

  • MYSQL_SSL_ENABLED
    Determines whether SSL is enabled for the MySQL connection. Set this to true in production environment.
    Example: false

  • DB_USERNAME
    The default is often root. In production, a non-root user with appropriate permissions is recommended.
    Example: root

  • DB_PASSWORD
    The password associated with the MySQL username.
    Example: root

  • DB_PORT
    The port used for MySQL communication. The default MySQL port is 3306, but this may differ based on your environment.
    Example: 3306

  • DB_NAME
    The name of the MySQL database used by Tombolo.
    Example: tombolo

  • DB_HOSTNAME
    The host of the MySQL database, typically localhost for local setups. For Docker, use the service name mysql_db.
    Example: localhost

5. Authentication and Authorization Configuration​

Tombolo offers two authentication methods: traditional authentication and Azure AD. By default, traditional authentication is enabled and is required for your ownership account. Regardless of whether you use Azure AD for authentication, the following three variables must be provided.

  • JWT_SECRET Avoid using predictable or short keys. Use a strong, random secret key generated by a secure method (such as using a cryptographically secure random generator)

  • JWT_REFRESH_SECRET Same as JWT secret the Refresh Secret must be unpredictable and long.

  • CSRF_SECRET This token is used by the application to protect against Cross-Site Request Forgery (CSRF) attacks. It must be a strong, unique value to ensure the integrity of requests and prevent unauthorized actions from malicious sources.

6. OAuth 2.0 (Azure) Configuration​

The first step to using Microsoft Entra ID for authentication is to register an application in Azure. Once registered, you will receive a Client ID and Tenant ID, which are crucial for this to work. You can also configure a redirect URI, which is a URL to be routed to when a user is authenticated.

  • TENANT_ID
    The tenant ID from Azure AD. You obtain this after registering your application in Azure AD.
    Example: your_tenant_id

  • CLIENT_ID
    The client ID from Azure AD. You obtain this after registering your application in Azure AD.
    Example: your_client_id

  • CLIENT_SECRET
    The client secret from Azure AD. You obtain this after registering your application in Azure AD.
    Example: your_client_secret

  • REDIRECT_URI The redirect URI from Azure AD. You obtain this after registering your application in Azure AD.
    Example: http://localhost:3000

7. Email Configuration​

Tombolo does not include a built-in SMTP server. To enable email functionality (e.g., notifications), you will need to configure an external SMTP server:

  • EMAIL_SMTP_HOST
    The SMTP host for sending emails.
    Example: smtp.mailserver.com

  • EMAIL_PORT
    The port number for the SMTP server.
    Example: 25

  • EMAIL_SENDER
    The default sender email address.
    Example: donotreply@tombolo.com

8. Security Configuration​

  • ENCRYPTION_KEY
    This key is used for hashing, encryption, and decryption operations within Tombolo. You can generate this key using OpenSSL:
    openssl rand -base64 32

  • API_KEY_DURATION
    The duration (in days) for which an API key remains valid. This key is used for accessing Tombolo data from external sources. The maximum duration is 365 days, and the default is 28 days.
    Example: 180

9. Integration-Specific Configuration​

If you have any integrations enabled and they have environment variables, they can be added to this configuration file as well. There is a placeholder section for those integration-specific variables. Please add them there.

Client Environment Variables​

Development Configuration​

  • GENERATE_SOURCEMAP
    Controls whether source maps should be generated. This is mainly used to suppress certain logs generated by Ant Design (antd). The value should be set to false.
    Example: false

  • PORT
    Defines the port on which the front-end React application will run.
    Example: 3001

  • REACT_APP_PROXY_URL
    Specifies the proxy URL for the React application, typically used to proxy API requests during development.
    Example: http://localhost:3000

LDAP Configuration​

  • REACT_APP_LDAP_SEARCH_ENABLED
    Enables or disables LDAP search functionality. Set this to false as LDAP is not currently used.
    Example: false

Authentication Configuration​

  • REACT_APP_AUTH_METHODS
    Specifies the authentication method to be used by the application. Available options are traditional and azure. For more details, refer to the APP_AUTH_METHOD variable in the server configuration. These values should be entered in a CSV format. You can use any combination of methods, but at least one must always be present to be able to authenticate to the application.

    Example: traditional,azure

Azure Configuration (only if using Azure AD for authentication)​

  • REACT_APP_AZURE_CLIENT_ID
    The client ID for Azure AD authentication.
    Example: your-azure-client-id

  • REACT_APP_AZURE_TENANT_ID
    The tenant ID for Azure AD authentication.
    Example: your-azure-tenant-id

  • REACT_APP_AZURE_REDIRECT_URI
    The URL Azure will redirect the user to after successful authentication. This must also be configured in Azure when registering the app.
    Example: http://localhost:3001/auth/callback

  • REACT_APP_AZURE_API_TOKEN_SCOPE
    The API token scope for Azure AD authentication.
    Example: api://your-api-id/.default

App Version​

  • REACT_APP_VERSION
    The version of the application, typically derived from the package version.
    Example: $npm_package_version