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.

To generate these secret tokens, you can use the following bash command: openssl rand -base64 32

  • 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​

Important: Azure AD authentication is optional, and you are not required to set Azure configuration variables

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:

Some services we recommend are: SendGrid, Mailgun, Azure ACS and Brevo

  • 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

  • EMAIL_USER (optional) The SMTP auth username.

    Example: testuser1

  • EMAIL_PASS (optional) The SMTP auth password.

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

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​

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

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

Authentication Configuration​

  • VITE_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)​

Important: Azure AD authentication is optional, and you are not required to set Azure configuration variables

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

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

  • VITE_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

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

App Version​

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