🔎

    Managing local secrets

    The Arkindex CLI has commands to manage secrets encrypted using GPG. Those secrets can be used to replace Arkindex secrets when running workers locally.

    Preparing your environment🔗

    To manage local secrets, you will need the following:

    Configuring a text editor🔗

    Secret editing works by decrypting, letting you type text, and re-encrypting. The secret only remains unencrypted when you are editing it. To allow this, the CLI needs to know about your editor.

    To configure a text editor🔗

    1. Add export EDITOR=<editor> to your shell's startup script (~/.bashrc, ~/.profile, ~/.zshrc, …), where <editor> is the command the CLI should run to open your editor.

      For example, export EDITOR=vim will make the CLI use Vim, and export EDITOR=gedit will make it use gedit.

    Creating a GPG key🔗

    If you do not have a GPG key already, you will need one.

    You can follow the "Set Up GPG Keys" section of DigitalOcean's tutorial on GPG to get started with GPG.

    Setting local secrets🔗

    With the CLI and a GPG key ready, you can now start managing local secrets.

    Creating or editing a secret🔗

    On your first attempt to create or edit a secret, you will be prompted for your GPG key. On subsequent attempts, you may be prompted for your GPG key's password if you have configured one. The CLI will then handle encrypting by itself.

    To create or edit your first local secret🔗

    1. Run arkindex secrets <name>, where <name> is the name of your secret.
    2. When prompted, select the GPG key that you want to use for secrets.
    3. Write your secret.
    4. Save and close the file.

    To create or edit a local secret🔗

    1. Run arkindex secrets <name>, where <name> is the name of your secret.
    2. Write your secret.
    3. Save and close the file.

    Deleting a secret🔗

    Deleting local secrets is not implemented in the CLI itself, but can be done using the filesystem.

    To delete a local secret🔗

    1. Open the folder at ~/.config/arkindex/secrets/.
    2. Delete the file named after your secret.

    Troubleshooting🔗

    This section describes common error resolutions and maintenance actions related to secret encryption.

    Encryption failed: invalid recipient🔗

    When saving a secret, the CLI shows the following error:

    Encryption failed: invalid recipient

    You will need to make sure that your GPG key's trust level is set to ultimate.

    To trust your GPG key🔗

    1. Run gpg --list-secret-keys. You will get an output similar to the following:

      /home/someone/.gnupg/pubring.kbx
---------------------------------
sec   rsa4096 2021-01-01 [SC]
      49EFBE4895CD1C4A3EDBA0D32E8A40B5FD3ACE4F
uid          [ unknown ] Arkindex <someone@example.com>
ssb   rsa4096 2021-01-01 [E]

    2. Run gpg --edit-key <KEY_ID> where <KEY_ID> is the 40-character key identifier for your key. In the example above, the identifier would be 49EFBE4895CDC4A3EDBA0D32EDA40B5FD3ACE4B.

    3. Type trust to edit the trust level and hit Enter.

    4. Type 5 to set to ultimate and hit Enter.

    5. Type save to save the changes and hit Enter.

    Using another GPG key for local secrets🔗

    If you picked the wrong key, lost the key, or have any other reason to use another GPG key, you will need to update the CLI's configuration file to get it to ask you for another key.

    To use another GPG key🔗

    1. Clone your CLI's configuration file, located by default at ~/.config/arkindex/cli.yaml, to back it up:

      cp ~/.config/arkindex/cli.yaml ~/.config/arkindex/cli.yaml.bak

    2. Open your CLI's configuration file in a text editor.

    3. Remove the line starting with gpg_key:.

    4. Save the file.

    5. Add a new secret using the CLI. You will be prompted for another key.