Setting up a secret

Tonic stores and encrypts your database credentials. If you prefer to use your own encryption key this page will show you how to set that up.

During initial installation

During initial installation you can setup your encryption key adding an environmental variable called TONIC_SECRET to both the tonic_worker and tonic_web_server containers. The TONIC_SECRET must be the same value in both containers and can be any string.


Setting up your own encryption key can also be accomplished post installation but the process is more complicated. This is because your data has already been encrypted with a different key (likely the default key used by Tonic). In order to make use of your own encryption key you can follow the steps below.

A word of caution

This process will irrevocably delete your database passwords and SSH tunnel keys and passphrases. You will be required to re-enter these credentials the first time you begin using your Tonic Workspace after the change is made.

Connect to the Tonic Database

In your initial setup you provided connection details to a Postgres database which Tonic uses as its internal data store. You'll first need to connect to this database through a postgres client such as psql. For more detailed instructions read these instructions on Connecting to the Tonic Database.

Backup your encrypted data

Before we make any changes we will back up the encrypted data so that we can revert these changes if needed.

Issue the following query to first create some columns to use to backup data:

"EncryptedPassword_Backup" TEXT,
"EncryptedBigQueryServiceAccount_Backup" TEXT,
"EncryptedSshPassphrase_Backup" TEXT,
"EncryptedSshPrivateKey_Backup" TEXT;

Now lets copy the original values into these backup columns

UPDATE "Databases" SET
"EncryptedPassword_Backup" = "EncryptedPassword",
"EncryptedBigQueryServiceAccount_Backup" = "EncryptedBigQueryServiceAccount",
"EncryptedSshPassphrase_Backup" = "EncryptedSshPassphrase",
"EncryptedSshPrivateKey_Backup" = "EncryptedSshPrivateKey";

Apply changes

Now let's delete the data that was encrypted with your old key.

UPDATE "Databases" SET
"EncryptedPassword" = null,
"EncryptedSshPrivateKey" = null,
"EncryptedSshPassphrase" = null,
"EncryptedBigQueryServiceAccount" = null;

Test your changes

We can now shut down Tonic, and follow the steps at the beginning of this document for setting up a key during an initial installation.

After that is complete, restart Tonic and login. You should notice that all of your workspaces are present, however, Tonic is unable to connect to the source database. This is because we deleted all of the passwords. You'll need to re-enter all of your passwords to each of your databases. Once that happens, you should be able to continue using Tonic and your passwords will be encrypted with your new secret.


If for some reason this process does not work you should revert your changes and reach out to [email protected] or through your companies typical support channel. In order to revert your changes run the following:

UPDATE "Databases" SET
"EncryptedPassword" = "EncryptedPassword_Backup",
"EncryptedSshPrivateKey" = "EncryptedSshPrivateKey_Backup",
"EncryptedSshPassphrase" = "EncryptedSshPassphrase_Backup",
"EncryptedBigQueryServiceAccount" = "EncryptedBigQueryServiceAccount_Backup";


The final step is to remove the columns you created to temporarily store your old passwords. If you plan on reverting your TONIC_SECRET you could consider keeping these columns in the database, however.

To delete the columns run:

ALTER TABLE "Databases"
DROP COLUMN "EncryptedPassword_Backup",
DROP COLUMN "EncryptedBigQueryServiceAccount_Backup",
DROP COLUMN "EncryptedSshPassphrase_Backup",
DROP COLUMN "EncryptedSshPrivateKey_Backup";