Installation

SecretVariable has two parts you install: the server (one container plus PostgreSQL) and the command-line tool, svar. This guide gets both running on your machine. To run it for a team on a real server with HTTPS, follow the self-hosting guide afterwards.

Requirements#

• Docker with Compose (to run the server), and git and openssl.
• Node.js 20 or newer and npm (to install the CLI). pnpm is only needed if you build the CLI from source.
• A gigabyte or two of free disk space for the images and the build.

1. Start the server#

The master key encrypts every project's data key. Generate it once and keep it safe: without it, stored data cannot be decrypted, and nobody can recover it.

$git clone https://github.com/OxygenOP/SecretVariable.git$cd SecretVariable$export SV_MASTER_KEY=$(openssl rand -hex 32)$echo "$SV_MASTER_KEY" > master.key && chmod 600 master.key   # keep this out of git$docker compose up -d

The first start builds the image, which takes a few minutes. Database migrations run automatically.

2. Create your account#

Open http://localhost:8080 and choose Create one on the sign-in page. Your password needs at least 10 characters. Every account starts with a personal workspace that you own.

Then create a project: New project, give it a name, and keep the default environments development, staging and production (you can change them later).

3. Install the CLI#

The CLI is published on npm as @secretvariable/cli. It is a single file with no dependencies and needs Node.js 20 or newer.

$npm install -g @secretvariable/cli

Check it:

$svar --version0.1.0

The package installs two names for the same program: svar (short, used throughout these guides) and secretvariable. We avoid sv because that is already the Svelte CLI and, on many Linux systems, a service-control command.

To update later, run npm update -g @secretvariable/cli. To remove it, run npm uninstall -g @secretvariable/cli.

Or build it from source#

If you prefer to run the code from the repository you cloned (you need pnpm):

$pnpm install$cd apps/cli$npm run build$chmod +x dist/index.js$mkdir -p ~/.local/bin && ln -sf "$PWD/dist/index.js" ~/.local/bin/svar

Make sure ~/.local/bin is on your PATH, then run svar --version.

4. Push your first .env#

Sign in, link your project folder, and upload the file you already have.

$svar login --server http://localhost:8080$cd ~/code/my-app$svar init                        # choose the organisation and project$svar push -m "first import"      # uploads .env as version 1 of development

init writes .secretvariable.json (a project id and the current environment, no secrets) so the commands know which project this folder belongs to. It is safe to commit.

On another machine, or after a teammate joins the project:

$svar login --server https://secrets.example.com$svar init$svar pull

Check that it works#

Troubleshooting#

docker compose refuses to start#

Compose stops with "Set SV_MASTER_KEY" when the variable is missing. Export it in the same shell, or put it in a .env file next to docker-compose.yml (copy .env.example).

Port 8080 is already in use#

Set a different host port: SV_PORT=8181 docker compose up -d, then use http://localhost:8181.

svar: command not found#

The link is not on your PATH. Add export PATH="$HOME/.local/bin:$PATH" to your shell profile, or run the tool directly with node apps/cli/dist/index.js.

"Cannot reach" the server#

Check the URL you passed to svar login. Use https:// for a real server; http:// is only for local testing.

Next: run it on a real server, or learn the CLI and the web app.