Install

evertap runs on one machine: a home server, a VPS, or the computer you develop on. That machine runs the databases and buckets in Docker. The same evertap command is also the CLI you use on your laptop and in CI, which needs no Docker (Connect from your laptop).

RequirementsCopy Anchor Link

On the machine that runs evertap:

• Linux on x64 or arm64, with Docker Engine 24 or later. Use 28.0 or later (28.3.3 or later with firewalld): older versions let other machines on your network reach what Docker publishes on 127.0.0.1, which includes every database and bucket, without going through evertap. The Doctor warns about it.
• Or macOS on Apple silicon or Intel, with Docker Desktop, OrbStack, or Colima, to use evertap on that Mac itself (local mode, see Choose how evertap is reached).
• Your user can use Docker without sudo. Add it to the docker group with sudo usermod -aG docker $USER, then log out and back in. Being in that group is as good as being root on that machine, so add only users you would trust with root.
• Disk space for the images evertap downloads: about 400 MB for each PostgreSQL version and 800 to 900 MB for each MySQL version you use.

On your laptop and in CI: Linux or macOS on x64 or arm64. On Windows, use the CLI inside WSL.

How Docker was installedCopy Anchor Link

evertap finds Docker's socket in this order: EVERTAP_DOCKER_SOCKET, a unix:// DOCKER_HOST, then the usual places of Docker Engine, Docker Desktop, OrbStack, Colima, and rootless Docker. Some installs need more:

• Docker from Snap cannot read files in hidden folders of your home, which includes evertap's data directory ~/.local/share/evertap, so databases fail to start. Install Docker from docker.com's packages instead, or set EVERTAP_DATA_DIR to a folder that is not hidden, such as ~/evertap, wherever you run evertap (see Configuration).
• Rootless Docker stops when you log out, and the databases with it. Run sudo loginctl enable-linger $USER and systemctl --user enable docker so it keeps running. The systemd unit below has no XDG_RUNTIME_DIR, so set EVERTAP_DOCKER_SOCKET=/run/user/<your uid>/docker.sock in its environment file.

The Doctor warns about both.

PortsCopy Anchor Link

Until you run evertap setup, the UI listens on 127.0.0.1 too, so nothing is reachable from other machines. Databases and buckets never listen anywhere but loopback: other machines reach them through the UI's address with evertap connect. The one exception is the entry for buckets reached from anywhere, which listens beside the UI (Security).

Install the binaryCopy Anchor Link

To run evertap itself in a container instead, see Run evertap in Docker.

curl -fsSL https://github.com/caru-ini/evertap/releases/latest/download/install.sh | sh

The script downloads the build for your system from the latest release, checks it against the release's SHA256SUMS, and installs it as /usr/local/bin/evertap, asking for sudo if it needs it. Give it settings on the sh side of the pipe:

• EVERTAP_VERSION=0.1.0 installs that release instead of the latest.
• EVERTAP_INSTALL_DIR=$HOME/.local/bin installs somewhere else.

curl -fsSL https://github.com/caru-ini/evertap/releases/latest/download/install.sh | EVERTAP_VERSION=0.1.0 sh

On a first install, the script ends with what to run next: on the machine that runs evertap, start it (Keep evertap running), then set it up; on a laptop, pair it.

By handCopy Anchor Link

From the releases page, download evertap-<os>-<arch>.tar.gz for your system and SHA256SUMS, then:

grep evertap-linux-x64.tar.gz SHA256SUMS | sha256sum -c   # on macOS: shasum -a 256 -c
tar -xzf evertap-linux-x64.tar.gz
sudo install -m 755 evertap-linux-x64/evertap /usr/local/bin/evertap

The archive also holds the license and the third-party notices. With the GitHub CLI, you can check that GitHub's release workflow built the archive:

gh attestation verify evertap-linux-x64.tar.gz --repo caru-ini/evertap

On macOS, a file downloaded with a browser is quarantined, and macOS refuses to run it. Remove the quarantine with xattr -d com.apple.quarantine evertap.

Keep evertap runningCopy Anchor Link

Every connection to a database or bucket goes through the evertap serve process. While it is stopped, the databases keep running in Docker but nothing reaches them.

With systemdCopy Anchor Link

The repository has an example unit, contrib/systemd/evertap@.service, that runs evertap serve at boot as the user named after the @. Run it as yourself: evertap keeps its data in that user's ~/.local/share/evertap, where evertap setup and the other commands you run find it.

curl -fsSLO https://raw.githubusercontent.com/caru-ini/evertap/main/contrib/systemd/evertap@.service
sudo cp evertap@.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now evertap@$USER

• The unit runs /usr/local/bin/evertap. If you installed it elsewhere, change ExecStart.
• Environment variables for the service go in /etc/evertap/evertap.env. Start from the example contrib/systemd/evertap.env, and set only what you need: a variable fixes its setting, and setup can no longer change it (Configuration).
• If you set EVERTAP_DATA_DIR there, set it in your shell too, or evertap setup and the other commands on that machine cannot find the running evertap.
• Read its log with journalctl -u evertap@$USER -f. On start, it says where it listens and what to do next.

Without systemdCopy Anchor Link

Run evertap serve in a terminal, or in tmux so it outlives your session. On macOS there is no example launchd job; run it in a terminal.

Set up and sign inCopy Anchor Link

On the machine running evertap, as the user that runs it, while it runs:

evertap setup

Setup asks how other machines reach evertap (see Choose how evertap is reached), asks only what that choice needs, and applies it without a restart. Then it signs in your first browser:

• In network and cloudflare mode, it prints a one-time sign-in link and a QR code. Open the link in a browser, or scan the code with your phone. It signs in one browser and expires in 10 minutes.
• In local mode, it opens a signed-in browser on this machine.

Without a terminal, give the answers as flags, and setup asks nothing:

evertap setup --mode local
evertap setup --mode network --listen 0.0.0.0
evertap setup --mode network --url https://evertap.example.com
CLOUDFLARE_API_TOKEN=<token> evertap setup --mode cloudflare --zone example.com
evertap setup --mode cloudflare --url https://evertap.example.com

Run evertap setup again to change your answers; it offers to keep the address you gave before. Once you are signed in, Settings in the UI can make the same changes, as long as they keep your browser connected.

Signing in laterCopy Anchor Link

• A new browser shows a code. On a device that is signed in, open /device (Clients → Add a device) and enter it.
• evertap signin-link, on the machine running evertap, prints another one-time link and QR code. Use it when no browser is signed in anymore.
• evertap open, on the machine running evertap, opens a signed-in browser there.

Check itCopy Anchor Link

evertap doctor

The Doctor, also a page in the UI, shows the Docker version and any warnings about it, the state of each service, whether each database and bucket entry answers, and which of your own Docker containers want the same ports.

Next, choose how evertap is reached if you have not, then connect from your laptop. Upgrading and uninstalling are in Limitations.