Skip to content

Latest commit

 

History

History
165 lines (141 loc) · 9.59 KB

env-config.md

File metadata and controls

165 lines (141 loc) · 9.59 KB

Environment Configuration

Starting from txAdmin v8.0.0, you can now customize txAdmin through TXHOST_* environment variables documented in this page.
Those configurations are usually required for Game Server Providers (GSPs) and advanced server owners, and allow them to force txAdmin and FXServer to use specific ports/interfaces, customize the location of the txData directory, force a max player slot count, etc.

Warning

The txAdminPort, txAdminInterface, and txDataPath ConVars, as well as the txAdminZapConfig.json file are now considered deprecated and will cease to work in an upcoming update.
If the new and old configs are present at the same time, the new one will take priority.
Setting TXHOST_IGNORE_DEPRECATED_CONFIGS to true will disable the old config and silence the respective warnings.

Important

All ConVars but serverProfile became TXHOST_* env vars, and you should avoid using it as the concept of txAdmin profiles will likely be deprecated soon.
If setting multiple servers, we strongly encourage you to set up separate txDatas for your servers. As otherwise the admins.json file will conflict.

Caution

Although the configuration below is useful for Game Server Providers (GSPs), this is in no way, shape, or form an endorsement or permission for anyone to become an unauthorized GSP.
Please refer to the FiveM Creator Platform License Agreement.

Setup

The specific way to set up those variables vary from system to system, and there are usually multiple ways even within the same system. But these should work for most people:

  • Windows:
    • Create env.bat with commands like: set VAR_NAME=VALUE
    • Before starting the server, run: call env.bat && your_server_command
  • Linux:
    • Create env.sh with commands like: export VAR_NAME=VALUE
    • Then load them with: source env.sh && ./your_server_command
  • Docker:
    • Create a .env file with the vars like: VAR_NAME=VALUE
    • Load it using the --env-file=.env flag in your docker run command.
  • Pterodactyl: You will likely need to contact your GSP or edit the "egg" being used.

Tip

For security reasons, those environment variables should be set specifically for the boot process and must not be widely available for other processes. If they are to be written to a file (such as .env), the file should only be readable for the txAdmin process and not its children processes.

Variables Available

General

  • TXHOST_DATA_PATH
    • Default value:
      • Windows: <fxserver_root>/../txData — sits in the folder parent of the folder containing fxserver.exe (aka "the artifact").
      • Linux: <fxserver_root>/../../../txData — sits in the folder that contains your run.sh.
    • The path to the txData folder, which contains the txAdmin logs, configs, and data. This is also the default place suggested for deploying new servers (as a subfolder). It is usually set to /home/container when running on Pterodactyl.
    • NOTE: This variable takes priority over the deprecated txDataPath ConVar.
  • TXHOST_GAME_NAME
    • Default value: undefined.
    • Options: ['fivem','redm'].
    • Restricts to only running either FiveM or RedM servers.
    • The setup page will only show recipes for the game specified
  • TXHOST_MAX_SLOTS
    • Default value: undefined.
    • Enforces the server sv_maxClients is set to a number less than or equal to the variable value.
  • TXHOST_QUIET_MODE
    • Default value: false.
    • If true, do not pipe the FXServer's stdout/stderr to txAdmin's stdout, meaning that you will only be able to see the server output by visiting the txAdmin Live Console page.
    • If enabled, server owners won't be able to disable it in txAdmin -> Settings -> FXServer page.
    • NOTE: We recommend that Game Server Providers enable this option.
  • TXHOST_API_TOKEN
    • Default value: undefined.
    • Options: disabled or a string matching /^[A-Za-z0-9_-]{16,48}$/.
    • The token to be able to access the /host/status endpoint via the x-txadmin-envtoken HTTP header, or the ?envtoken= URL parameter.
    • If token is undefined: endpoint disabled & unavailable.
    • If token is string disabled: endpoint will be publicly available without any restrictions.
    • If token is present: endpoint requires the token to be present.

Networking

  • TXHOST_TXA_URL:
    • Default value: undefined.
    • If present, that is the URL that will show on txAdmin as its public URL on the boot message.
    • This is useful for when running inside a container using 0.0.0.0:40120 as interface/port.
  • TXHOST_TXA_PORT
    • Default value: 40120.
    • Which TCP port txAdmin should bind & listen to.
    • This variable cannot be 30120 to prevent user confusion.
    • NOTE: This variable takes priority over the deprecated txAdminPort ConVar.
  • TXHOST_FXS_PORT
    • Default value: undefined.
    • Forces the FXServer to bind to the specified port by enforcing or replacing the endpoint_add_* commands in server.cfg.
    • This variable cannot be 40120 to prevent user confusion.
  • TXHOST_INTERFACE
    • Default value: 0.0.0.0.
    • Which interface txAdmin will bind and enforce FXServer to bind to.
    • NOTE: This variable takes priority over the deprecated txAdminInterface ConVar.

Provider

  • TXHOST_PROVIDER_NAME
    • Default value: Host Config.
    • A short name to identify this hosting provider.
    • The value must be between 2 and 16 characters long and can only contain letters, numbers, underscores, periods, hyphens, and spaces. Must not start or end with special chars, and must not have two subsequent special chars.
    • This will usually show in warnings regarding configuration or user actions that go against any TXHOST_* variable.
  • TXHOST_PROVIDER_LOGO
    • Default value: undefined.
    • The URL for the hosting provider logo which will appear at the login page.
    • The maximum image size is 224x96.
    • You can create a theme-aware URL by including a {theme} placeholder in the URL, which will be replaced by light or dark at runtime, depending on the theme being used, eg. https://.../logo_{theme}.png.

Defaults

  • TXHOST_DEFAULT_DB<HOST|PORT|USER|PASS|NAME>
    • Default value: undefined.
    • To be used only for auto-filling the config steps when deploying a new server and can be overwritten during manual deployment or after that by modifying their server.cfg.
    • All the values will be considered strings, and no validation will be done to them.
  • TXHOST_DEFAULT_CFXKEY
    • Default value: undefined.
    • To be used only for auto-filling the config steps when deploying a new server and can be overwritten during manual deployment or after that by modifying their server.cfg.
    • The value should be a cfxk_xxxxxxxxxxxxxxxxxxxxx_xxxxxx key, which individuals can obtain in the Cfx.re Portal.
    • This is also very useful for developers who need to go through the txAdmin Setup & Deployer frequently.
  • TXHOST_DEFAULT_ACCOUNT
    • Default value: undefined.
    • This variable is used by GSPs for setting up an admins.json automatically on first boot.
    • It contains a username, FiveM ID, and password (as bcrypt hash) separated by colons:
      • Username: If a FiveM ID is provided, this must match the username of the FiveM account used by the second parameter. Otherwise, it accepts any username valid for txAdmin accounts (same rule used by the FiveM Forum).
      • FiveM ID: The numeric ID of a FiveM account, same as the one visible as in-game identifier. For instance, the value should be 271816 for someone with the in-game identifier fivem:271816. When set, the admin will be able to login using the Cfx.re button instead of requiring a password.
      • Password: A bcrypt-hashed password to be used as the "backup password".
    • The account must at least have either FiveM ID or password set. If an account has no password, on first access the owner will be queried to change their password.
    • Examples:
      • tabarra:271816
      • tabarra:271816:$2a$11$K3HwDzkoUfhU6.W.tScfhOLEtR5uNc9qpQ685emtERx3dZ7fmgXCy
      • tabarra::$2a$11$K3HwDzkoUfhU6.W.tScfhOLEtR5uNc9qpQ685emtERx3dZ7fmgXCy

Note

More variables are still being considered, like options to configure reverse proxy IPs, security locks, etc.
Please feel free to provide feedback and suggestions.

Examples

Setting up a dev server on Windows with a env.bat file:

@REM Deployer defaults
set TXHOST_DEFAULT_CFXKEY=cfxk_11hIT156dX0F0ekFVsuda_fQ0ZYS
set TXHOST_DEFAULT_DBHOST=127.0.0.1
set TXHOST_DEFAULT_DBPORT=3306
set TXHOST_DEFAULT_DBUSER=root
set TXHOST_DEFAULT_DBPASS=4b6c3_1919_ab04df6
set TXHOST_DEFAULT_DBNAME=coolrp_dev

@REM Prevent conflicting with main server
set TXHOST_DATA_PATH=C:/test-server/txData
set TXHOST_FXS_PORT=30125
set TXHOST_MAX_SLOTS=8

Setting a GSP configuration on Docker with a .env file:

# So txAdmin suggests the right path during setup
TXHOST_DATA_PATH=/home/container

# Deployer defaults
TXHOST_DEFAULT_DBHOST=123.123.123
TXHOST_DEFAULT_DBPORT=3306
TXHOST_DEFAULT_DBUSER=u538241
TXHOST_DEFAULT_DBPASS=4b6c3_1919_ab04df6
TXHOST_DEFAULT_DBNAME=db538241

# Customer FiveM-linked account
TXHOST_DEFAULT_ACCOUNT=tabarra:271816

# Provider details
TXHOST_PROVIDER_NAME=ExampleHosting
TXHOST_PROVIDER_LOGO=https://github.com/tabarra/txAdmin/raw/master/docs/banner.png