Skip to main content

Environment Variable

Environment Variable​

NameDefault ValueDescription
PORT11000Gateway service port number
SECRETtailchatencryption key, used for JWT. Must be set to a long random string in production, the default value is public and allows anyone to forge user tokens
STATIC_HOST"{BACKEND}"Externally accessible static service host, used for file service access, the default is the dynamic server address inferred from the front-end request, if it is expected to be stored in a third-party OSS, it needs to be modified
STATIC_URL"{BACKEND}/static/"Externally accessible static service complete address prefix, used for file service access, the default is the dynamic server address inferred from the front-end request, if it is expected to be stored in a third-party OSS Modify, if this variable is set, the above STATIC_HOST value is invalid
API_URLhttp://127.0.0.1:11000Externally accessible url address, used for issuer issuance on open platforms or as a fallback for file services
MONGO_URL-Database service address
REDIS_URL-Redis service address
REGISTER_IP_LIMIT_PER_HOUR3Maximum registration attempts per IP in a rolling hour; positive integer
REGISTER_IP_LIMIT_PER_DAY10Maximum registration attempts per IP in a rolling 24 hours; positive integer
MINIO_URL-File service address (minio)
MINIO_USER-File service username
MINIO_PASS-File service password
MINIO_BUCKET_NAMEtailchatfile service bucket name
MINIO_PATH_STYLEfalseWhether to use path-style s3 communication format, true is Path Style, false is Virtual hosted style
MINIO_SSLfalseWhether to use SSL to connect storage, if "1" or "true" enable SSL
SMTP_SENDER-Mail service sender (example: "Tailchat" example@163.com)
SMTP_URI-mail service connection address (example: smtp://username:password@smtp.example.com/?pool=true)
FILE_LIMIT1048576File/image upload size limit, the default is 1m, please enter a number(unit: byte)
EMAIL_VERIFY-Whether to enable email verification, if it is "1" or "true", add email verification control when registering
REQUEST_TIMEOUT10000Number of milliseconds to wait before reject a request with a RequestTimeout error. Disabled: 0
TIANJI_SCRIPT_URL-Script Url of Tianji if you wanna monitor Tailchat user usage, you can get it in code modal in Tianji website (example: https://tianji.example.com/tracker.js)
TIANJI_WEBSITE_ID-Tianji website id
DISABLE_MESSAGEPACK-Whether to disable using messagepack as parser for socketio in openapi, if "1" or "true" turn off this method
DISABLE_LOGGER-Whether to disable the log output, if "1" or "true" turn off the log on the fly
DISABLE_TRACING-Whether to disable the Tracing function (enabling it can save a lot of logs), if "1" or "true" turn off the log on the fly
DISABLE_USER_REGISTER-Whether to disable the user register, if "1" or "true" turn off this method
DISABLE_GUEST_LOGIN-Whether to disable the guest login, if "1" or "true" turn off this method
DISABLE_CREATE_GROUP-Whether to disable user create group, if "1" or "true" turn off this method
DISABLE_PLUGIN_STORE-Whether to hide user plugin store entry, if "1" or "true" turn off this method
DISABLE_ADD_FRIEND-Whether to hide user add friend entry, if "1" or "true" turn off this method
DISABLE_TELEMETRY-Whether to disable send telemetry report to msgbyte to help us improve, its anonymous, if "1" or "true" turn off telemetry

Some examples of environment variables can be seen: https://github.com/msgbyte/tailchat/blob/master/server/.env.example

Registration IP limits and reverse proxies​

Regular and guest registration share the same Redis quota: by default, 3 attempts per rolling hour and 10 per rolling 24 hours. IPv4-mapped IPv6 addresses share the IPv4 quota; IPv6 addresses in the same /64 share a quota. Users behind the same NAT also share a quota, so adjust the limits to your deployment. Invalid limits prevent startup.

The service checks the hourly window, then the daily window, before password hashing or database writes. Attempts that pass a window consume its quota even if a later check or registration fails. Deleting an account does not restore quota. Rejections return HTTP 429 (REGISTER_IP_LIMITED) with retryAfterMs and windowSeconds. Missing IP metadata or an unavailable Redis returns 503 and prevents registration. Internal calls to user.register or user.createTemporaryUser must supply a valid meta.ip; the built-in CLI supplies loopback.

Registration limits and last login IP records use the same IP source: the first address in X-Forwarded-For, then X-Real-IP, then the connection peer's IP. Socket.IO uses the same rule. The reverse proxy must sanitize forwarding headers and the backend must only be reachable through that proxy, so clients cannot choose the IP used for quotas.

All replicas must share Redis and use the same limits, API_URL, broker namespace and cache prefix. Quotas are isolated by that prefix, namespace and API_URL; separate deployments sharing Redis must use distinct values or separate Redis databases. Redis supplies the clock and atomically reserves each slot. Restart all replicas after configuration changes. Changing a limit starts a new quota for that window; old keys expire within 24 hours of their last use. Redis data loss or cache clearing resets quotas, so retain Redis data when restarting the deployment.

Use files to configure environment variables​

    • If starting locally, copy .env.example to .env and edit
    mv .env.example .env
    vi .env

  • If it is started by docker-compose, you can directly edit docker-compose.env, and use docker compose up -d directly after the modification to take effect

About the use of environment variables with spaces​

If your environment variable value contains spaces, in order for the system to recognize that this is a complete string instead of treating spaces as separators. You need to wrap a double quotes around the outside.

For example:

SMTP_SENDER="\"Tailchat\" example@163.com" # If there are repeated double quotes, they need to be escaped with an escape character
caution

Some environment variable modifications may need to clear the cache to take effect

How to clear the cache​

Changes to some environment variables may involve cache updates, such as FILE_LIMIT, because config data needs to be sent to the client.

Therefore, it may appear that after modifying the environment variable, the performance on the client is still the same as before. At this point you need to clear the old cache for the update to take effect.

There are several options for clearing the cache:

  • Execute docker compose down then run docker compose up -d. This is because the data of the redis service is not persisted, shutting down and restarting the service is equivalent to a brand new environment
  • Manually enter the redis service to clean up the cache items whose name contains config.client, which contains the configuration items returned to the client
  • Enter the cache management page of the admin management system. Click the Clean Configuration Cache button