Skip to main content

​
Use a database password in a plugin configuration

This example uses a template. SimpleCloud leaves the reference in the template and inserts the password into the running server’s copy before the process starts.
1

Create the secret

Open Settings > Secrets in the dashboard and select Add secret. Enter DATABASE_PASSWORD as the key, enter the password as the value, then select Encrypt & save.At least one serverhost must be connected before you can add a secret. After saving, the dashboard shows the key but cannot display the value again.
2

Add the reference to the template

Open Files, select the serverhost, and edit the plugin configuration in the matching template. For example, place this file at templates/lobby/plugins/DatabasePlugin/config.yml:
templates/lobby/plugins/DatabasePlugin/config.yml
Adapt the path and surrounding settings to your plugin. Keep the secret reference exactly as shown.For a persistent server that already has this file, stop the server and edit its existing configuration from the server’s Files page instead. A template does not replace an existing persistent-server file.
3

Start a server with the new value

Start a new lobby server. If you edited a persistent server, start it again. SimpleCloud copies the template when needed, replaces the reference in the running file, and then starts the server process.Servers that are already running keep the value with which they started.
4

Check the result

Confirm that the plugin connects successfully. When you open the running file in the dashboard, the editor still shows {{ secrets.DATABASE_PASSWORD }} instead of the password. This is intentional.

​
Use secrets in configurators and workflows

The same {{ secrets.KEY }} reference works in a Configurator. Use it as a value, not as part of the target file path:
Workflow parameters can also use secrets. This upload step reads its bearer token at runtime, so the token does not appear in the workflow file:
Create BACKUP_TOKEN under Settings > Secrets before running this workflow. The upload source must already exist.

​
Rotate or delete a secret

Open the action menu next to a key under Settings > Secrets and select Rotate secret to replace its value. The key stays the same, so you do not need to edit its references. Restart each affected server to apply the new value. During a rolling restart, old and new instances can temporarily use different values. Remove every reference before deleting a secret. A server does not start if one of its configuration files requires a missing secret. A workflow that uses a missing secret cannot receive its value.
SimpleCloud creates and manages VELOCITY_SECRET for secure proxy forwarding. Do not rotate or delete it manually. A changed forwarding secret must reach the proxy and every backend server together, or connections between them will fail.

​
How secrets are protected

Every serverhost in the network can use every key. Use separate networks when values must not be shared between hosts. When you save a secret, the dashboard encrypts it in your browser with the network’s public key. The controller stores the encrypted value and cannot decrypt it. The connected serverhosts share the corresponding private key and decrypt secrets in memory when a server or workflow needs them. During server startup, SimpleCloud runs the configured start workflows first. It then replaces secret references in copied or configured text files and starts the server process. The source template keeps its reference. SimpleCloud records only the managed file locations, not the secret values. That record lets later rotations update the same locations. The running server needs the real value, so SimpleCloud writes it to the running configuration file. Users and processes with direct access to that serverhost or server directory can read it. Secrets keep the value out of templates and workflow files. The controller stores only ciphertext, but the software using the secret receives the real value. Secret keys and values have these limits:
  • A key starts with a letter or underscore and contains up to 64 letters, numbers, underscores, or hyphens. The dashboard converts new keys to uppercase.
  • A value cannot be empty and can contain up to 16 KB. Whitespace and line breaks are preserved.
  • References are case-sensitive. Copy the reference shown under Settings > Secrets to avoid a mismatch.
  • Use references in text configuration files. Do not put them in JAR files, worlds, databases, or archives.

​
Troubleshooting

Start or reconnect a serverhost. The first connected serverhost registers the network’s encryption key, after which the dashboard enables secret creation.
Open Settings > Secrets and compare the key with the text inside {{ secrets.KEY }}. Keys are case-sensitive. Add the missing key or correct the reference before starting the server.
Rotation does not change a process that is already running. Restart every server and rerun every manual workflow that should use the new value.
The dashboard file editor and downloads replace managed plaintext with the reference before sending the file to your browser. Check the application behavior or its connection result instead of looking for the value in the editor.
Check the serverhost log for Missing secret or Failed to apply secrets. Create the named key or remove its reference, then start the server again. If one required secret is missing, SimpleCloud leaves all secret-managed files unchanged.