# Hosting your SecureVault server SecureVault keeps your vault in a database that you run yourself. The whole server is one MariaDB database (`secure_vault`) and one database user (`vault_user`) that may do nothing outside it. The app creates its own tables the first time it connects. Your devices (the SecureVault app, the agent module) connect to it over your home network or over Tailscale. This page is for a person. If an AI agent sets the server up for you, point it at `agent-setup.md` on the SecureVault site instead; it contains the same steps written for an agent. What is in the database: passwords, 2FA secrets, notes, security questions, backup codes, door codes and login guides are encrypted on your devices before they are stored (AES-256-GCM, key from your master password). Account names, usernames, e-mail addresses, websites and folders are stored in plain text. So the database must stay on networks you trust: **never forward its port (3306) from your router to the internet.** ## Which way to host | You have | Use | Effort | | --- | --- | --- | | A Raspberry Pi, a home server or an always-on PC with Debian, Ubuntu, Raspberry Pi OS, Arch Linux or Fedora | **The installer** (`install.sh`) | One command | | A Mac, a Windows PC, a NAS or any other computer with Docker | **Docker** (`docker-compose.yml`) | Three commands | | A Linux machine where MariaDB already serves something else | **Docker** (the installer stops rather than change that MariaDB) | Three commands | | Only an Android phone | **Termux** (`termux.sh`): for advanced users, with conditions | See that section | The server must be on whenever a device wants the vault. A laptop that sleeps is a poor server. Everything below runs from the kit folder (the folder this file is in). ## What was tested Every claim on this page comes from a test that was run on 2026-11-20 (the phone on 2026-11-19). The tests ran in containers on one x86-64 Linux desktop, not on separate physical machines. | Way of hosting | Tested on | MariaDB | Not tested | | --- | --- | --- | --- | | Installer | Debian 12 and 13, Ubuntu 22.04 and 24.04, Arch Linux, Fedora 45, each in a container with systemd: install, second run, backup, restore, nightly timer, restart of the system, firewall, uninstall. Debian 12, Arch and Fedora also without systemd (`--manual-start`), and a bare Arch where neither a firewall rule nor a scheduler is possible | 10.6 to 13.0 (whatever the system ships) | Real hardware and virtual machines; SELinux (see Troubleshooting); Tailscale itself (a stand-in address was used) | | Installer on a Raspberry Pi | Debian 12 for 64-bit ARM, emulated, without systemd and without the firewall rule | 10.11 | A real Raspberry Pi and Raspberry Pi OS itself | | Docker | Docker Engine 29 with Compose 5 on Linux, using only `docker compose` commands (no shell scripts on the computer), with the clients on the same computer | 11.4 (the image `mariadb:11.4`) | **Docker Desktop on macOS and on Windows was not run**, and no shell but bash. A client on another machine (the published port was never put on a real home-network address). What could differ is named in the Docker section | | Android phone | Samsung Galaxy A54, Android 16, Termux 0.118.3 | 13.0 | Start after a reboot, Termux swiped away, an unplugged phone in deep sleep, and more: see that section | Each server was checked from outside with the app's own database library (Dart `mysql1`, both the published one and the patched copy in the app's release branch), the agent module's library and settings reader (Node `mysql2`), and the `mariadb` command-line client: sign-in, the app's tables, text in several scripts and emoji, an 80 000-byte field, and that `vault_user` is refused everything outside its database. ## The installer (Debian, Ubuntu, Raspberry Pi OS, Arch Linux, Fedora) ```sh sudo ./install.sh ``` It asks one question (is this plan right?) and then: - installs MariaDB with your system's package manager if it is missing (on Arch it also creates the data directory), and three small packages where they are missing: `iproute2` (to read the machine's addresses), `nftables` (the firewall rule) and `qrencode` (the QR code). Each gets its own `==> Installing ...` line, - creates the database and `vault_user` with a generated 32-character password and only these rights on that one database: select, insert, update, delete, create, alter, index, references, - makes MariaDB listen on the home network, and limits both the firewall and the account to private addresses (10.x, 172.16-31.x, 192.168.x, and Tailscale's 100.64-127.x if Tailscale is running). MariaDB itself then listens on every address of the machine (`0.0.0.0`), so that a changed address does not stop it; the firewall rule and the account are what keep everything else out, - prints what the app asks for, with a `securevault://connect?c=...` line and a QR code, - ends with a status table and one line that starts with `RESULT:`. In the app, on **Connect to your server**, paste that line (or scan the QR code with a phone). The connect line carries this machine's address. Give the machine a fixed address in your router (a DHCP reservation), or the app loses the server when the address changes. How a run ends is the same every time, for you and for a script or an AI agent: ``` SecureVault server: status database ok vault_user signs in over the network on port 3306 (MariaDB 10.11.19) starts after restart yes systemd starts MariaDB (mariadb.service is enabled) firewall rule yes nftables: port 3306 answers private addresses only; loaded at every start nightly backup yes systemd timer securevault-backup.timer RESULT: complete ``` | Last line | Exit code | Meaning | | --- | --- | --- | | `RESULT: complete` | 0 | All four are in place | | `RESULT: set up, but without: ...` | 0 | Everything you asked for is in place; the things named were switched off on purpose or not asked for (for example no `--backup-timer`) | | `RESULT: incomplete: ...` | 3 | The database is set up, but something you asked for is missing; the `no` rows say what and what to do | | no `RESULT:` line, an `ERROR:` line instead | 1 | It stopped there; the message says why | It needs root because it installs a package, writes MariaDB settings and adds a firewall rule. What it writes: | What | Where | | --- | --- | | MariaDB settings (where it listens) | `/etc/mysql/mariadb.conf.d/99-securevault.cnf` (Debian, Ubuntu), `/etc/my.cnf.d/zz-securevault.cnf` (Arch, Fedora) | | Password, `server.json`, the connect line | `/etc/securevault/` (root only) | | Firewall | its own nftables table `inet securevault`, loaded at every start by `securevault-firewall.service` (the system's own `nftables.service` is not used and may stay off); with ufw or firewalld active, rules in those instead | | Commands | `/usr/local/sbin/securevault-server` (the installer itself), `securevault-backup`, `securevault-restore` | Useful options (`./install.sh --help` lists all): | Option | What it does | | --- | --- | | `--tailscale` | Listen on this machine's Tailscale address only. Best when you use the vault away from home | | `--address IP` | Listen on one private address of this machine only | | `--backup-timer` | Also turn on the nightly backup | | `--no-firewall` | No firewall rule, and you accept a server without one (stays so on later runs; `--firewall` turns it back on) | | `--manual-start` | Set it up on a system without systemd (see below) | | `--port N` | Another port than 3306 | | `--tls` | Require an encrypted connection (see "TLS") | | `--hide-secrets` | Do not print the password or the connect line (the default when the output is not a terminal) | | `--yes` | Do not ask | Later: ```sh sudo securevault-server --show # the connection details again sudo securevault-server --check # can vault_user sign in on every address? and the status table again sudo securevault-server --reset-password # new password; every device must connect again sudo securevault-server --tailscale # change where it listens (any option can be changed by running it again) ``` Running the installer again changes nothing that is already right: it keeps the password and does not restart MariaDB. It stops, and changes nothing, when: - **MariaDB is already installed and holds other databases or accounts.** The installer would change where that whole server listens and restart it. Use Docker instead, or, if you decide it is fine, run it with `--use-existing-mariadb`. - **Oracle MySQL is installed.** It only sets up MariaDB. Use Docker. - **The machine has a public internet address** (a rented server, for example) and you did not choose `--tailscale` or `--address`. - **The system does not run systemd** (a container, some WSL setups). Nothing there would start the database again after a restart of the machine, so it is not a suitable host as it is: use Docker, or another machine. If you accept a database that you start by hand after every restart, run the installer with `--manual-start`. The status table then says `starts after restart no`, and after each restart you run: ```sh sudo securevault-server --start # starts the database, loads the firewall rule, prints the status table ``` On such a system the nightly backup (`--backup-timer`) works only if cron is running; otherwise `sudo securevault-backup` by hand is the only backup. `--manual-start` is remembered on later runs. If the firewall rule cannot be added (for example `Operation not permitted` in a container or on a restricted virtual server), the run ends with `RESULT: incomplete: firewall rule`. The database port then answers every machine that can reach this one, and only the account's limit to private addresses guards it. Remove the cause and run the installer again, or accept it with `--no-firewall`. ## Docker (any computer: Linux, macOS, Windows) You need Docker with Compose (Docker Desktop on macOS and Windows; Docker Engine with the compose plugin on Linux). Nothing else: the helper scripts run in containers. Open a terminal in the kit folder and keep that folder: it will hold your settings (`.env`) and your backups. First find the address of this computer on your home network (for example `192.168.1.20`), or its Tailscale address (`100.x.y.z`) if you use Tailscale: - Linux: `ip -4 -brief addr` - macOS: `ipconfig getifaddr en0` (Wi-Fi is usually `en0`) - Windows (PowerShell): `ipconfig` and read "IPv4 Address" - Tailscale, any system: `tailscale ip -4` Give the computer a fixed address in your router, or the vault moves when the address does. ```sh docker compose run --rm setup --init --address 192.168.1.20 # once: writes .env with generated passwords docker compose up -d # starts the database and the daily backup docker compose run --rm setup # prints what the app asks for docker compose run --rm qr # the connect line as a QR code, for a phone ``` On Linux, put `sudo` in front of `docker` unless your user is in the `docker` group. On Linux you can also run the helper directly, and it finds the address itself: `./connect-info.sh --init`, then `./connect-info.sh`. What runs: `securevault-db-1` (MariaDB 11.4, data in the Docker volume `securevault_securevault-data`) and `securevault-backup-1` (one backup a day into `./backups`). Both have the restart policy `unless-stopped`, so Docker starts them again when it starts (tested by restarting the containers, not by restarting Docker or the computer). That only helps if Docker itself starts with the computer. On Linux check `systemctl is-enabled docker.service`: with `disabled`, Docker starts only when first used and the vault stays down after a restart until then (`sudo systemctl enable docker.service` changes that; not tested here). How the Docker setup differs from the installer: - The port is published on the one address you gave, and that is the network limit to rely on. In the tests (clients on the same computer) MariaDB inside the container saw every connection as coming from Docker's own network, so the account's address limits could not tell one client from another. How a client on another machine appears was not tested. Never use `0.0.0.0` on a computer with a public address: Docker's published ports go around ufw and most firewalls. - No firewall rule is added and there is no TLS option. For use away from home, give the Tailscale address to `--init --address`. - Listening on both the home network and Tailscale needs two published addresses, which this file does not do. Use the Tailscale address for both (it also works at home), or the installer. **Not tested on Docker Desktop (macOS, Windows).** The steps above were run on Linux only. Things that can differ there, and were not checked: whether publishing on one specific address works the same way; the firewall of Windows or macOS asking for (or silently refusing) incoming connections on the port; file sharing for the kit folder. Also keep the kit's files with Unix line endings (unpack the `.tar.gz` with `tar -xzf`; do not let an editor or Git convert them). If a step fails there, the Troubleshooting section says what to look at. To use another port: `--init --address --port 3307`. To change the address later: edit `BIND_ADDRESS` in `.env`, then `docker compose up -d`, then `docker compose run --rm setup`, and connect each device again. ## Android phone (Termux) For advanced users. A feasibility test on one phone went well, but three things that decide whether you can rely on it were not tested. Read both lists before you choose this. What it is: MariaDB running inside the Termux app, listening on the phone's Tailscale address only. **Conditions** 1. Tailscale on the phone and on every device that uses the vault. Android runs one VPN at a time, so a phone that needs another VPN app cannot do this. 2. Termux from F-Droid or GitHub (not the Play Store), and the Termux:Boot app, opened once, for a start after a reboot. After a reboot the phone must be unlocked once before anything starts. 3. Termux holds a wake lock all the time (battery). Set battery use of Termux and Tailscale to "Unrestricted" in Android's settings. 4. No firewall, and no fixed MariaDB version: Termux installs whatever is current (13.0.2 on the test day). 5. The vault is reachable only while the phone is on, has a network and Termux is alive. Backups must be pulled to another device: a lost phone otherwise takes the vault and its backups with it. **Set-up**, in Termux, with the kit unpacked on the phone: ```sh pkg install -y mariadb bash termux.sh ``` It ends with one line saying where the connection details are: `~/securevault/server.json` and `~/securevault/connect.txt` (the `securevault://connect?c=...` line). It never prints the password. On the same phone, show the line with `cat ~/securevault/connect.txt`, copy it and paste it into the app. `termux.sh` is, apart from its comments, the script that was run on the test phone. In that run mariadb was already installed, a different port was used, and the boot script was switched off, so three lines of it did not run there: `pkg install`, the default port 3306, and writing `~/.termux/boot/start-securevault`. **Tested on the phone** (Samsung Galaxy A54, Android 16, 2026-11-19), in two parts: - *With this script, run once:* it created the data directory, started the server, made the database, the user and the two files in 13 seconds; a desktop then signed in over Tailscale with the password from its `server.json`, and the connect line decoded to the same settings. - *On the same phone, with the same MariaDB and the same settings, but set up by hand and kept alive by a separate small restart loop:* the app's and the agent module's database libraries over Tailscale; text and emoji; back by itself 8 seconds after the server process was killed, with nothing lost; a backup (copied to a desktop and checked there) and a restore into a scratch database; two idle periods of 16 minutes with the screen off (the phone was charging). The keep-alive loop that `termux.sh` writes (`run.sh`) does the same job but is not the one that was killed and watched. **Not tested** | What | Why it matters | | --- | --- | | Start after a reboot (Termux:Boot) | Until you have rebooted the phone and seen it come back, assume it does not | | Termux swiped away from the recent-apps list | May stop the server | | An unplugged phone in deep sleep, with and without the wake lock | The idle tests ran on a charger | | Battery cost | Could not be measured | | Switching between Wi-Fi and mobile data with a connection open | | | Android's process killer over days | The test ran 45 minutes | | Running `termux.sh` a second time, the `stop.sh` and `backup.sh` it writes, and removing everything | Read below | | Downloading and unpacking the kit inside Termux | Only the script itself was run | Day to day. These use the files the script writes. On the phone the same dump and restore commands were run by hand; these exact lines were not: ```sh ssh -p 8022 securevault/backup.sh > secure_vault-$(date +%F).sql.gz # from another device; then: gzip -t zcat | mariadb --defaults-file=$HOME/securevault/my.cnf secure_vault # restore, on the phone ~/securevault/stop.sh # stop ``` Do not run `termux.sh` again while the server is running: it would start a second keep-alive loop. ## Using the vault away from home Use [Tailscale](https://tailscale.com/download) (free for personal use): install it on the server and on every device, and sign in to the same account. Then: - installer: `sudo securevault-server --tailscale` (only Tailscale), or run `sudo securevault-server --lan` again after installing Tailscale (home network and Tailscale; the app tries both addresses), - Docker: give the Tailscale address to `--init --address`, and connect each device again with the new line. Do not forward port 3306 from your router to the internet, and do not put the server on a public address. The account names and usernames in the vault are not encrypted, and a database port on the internet is found and attacked within hours. The installer refuses a public address unless you pass `--allow-public`; this page does not recommend it. ## TLS (installer only) Tailscale already encrypts everything between your devices. On a home network the secret fields are encrypted before they leave the device, but names and usernames travel as they are; `--tls` encrypts the whole connection. ```sh sudo securevault-server --tls # back: --no-tls ``` It makes a self-signed certificate and requires TLS from `vault_user`. Then: - the app needs a version with a **TLS** switch on its server screen (it encrypts but does not verify the certificate). The app version without that switch cannot connect to a server that requires TLS; - the agent module verifies the certificate: copy `ca.pem` (the installer prints where it is) to the computer the agent module runs on and set `SECURE_VAULT_DB_TLS_CA` to its path. Tested on Debian 12, Arch Linux and Fedora 45 with all three clients. ## Backup A backup is one compressed file. **A backup that stays on the server does not survive the server**: copy the files to another device or disk regularly. | | Installer | Docker | | --- | --- | --- | | Automatic | `sudo securevault-backup --install-timer` (or `--backup-timer` at install): every night between 03:15 and 03:30 in the machine's own time zone (`date +%Z`); `systemctl list-timers securevault-backup.timer` shows the next run | Always on: one a day | | One now | `sudo securevault-backup` | `docker compose run --rm backup --once` | | Where | `/var/backups/securevault/` (root only) | `./backups/` in the kit folder | | Kept | the newest 14 (`--keep N`) | the newest 14 | ## Restore Close the app on every device first. A restore replaces everything in the database; it saves the current state first (`secure_vault-pre-restore-...`; these safety copies are never deleted automatically) and asks you to type `restore`. | | Installer | Docker | | --- | --- | --- | | List | `sudo securevault-restore` | `docker compose run --rm restore` | | Newest | `sudo securevault-restore --latest` | `docker compose run --rm restore --latest` | | A file | `sudo securevault-restore /path/file.sql.gz` | put the file in `./backups/`, then `docker compose run --rm restore file.sql.gz` | `vault_user` and its password are not part of a backup; they belong to the server. So a backup can be restored on another server, and the devices then connect with that server's line. Moving a vault this way was tested from Debian 12 to Docker, from Arch to Debian 12 and from Docker to Arch. ## Update - **MariaDB, installer:** it is a normal package of your system; your usual system updates update it. - **MariaDB, Docker:** `docker compose pull`, then `docker compose up -d`. The image is pinned to the 11.4 series. (No newer 11.4 image existed on the test day, so `pull` itself had nothing to do; starting the same data with a newer MariaDB image, 11.4 to 11.8, was tested and upgraded it in place.) - **The kit:** unpack the new kit and run `sudo ./install.sh` again (it keeps your password and settings). For Docker, copy the new files over the old ones in your kit folder, keeping `.env` and `backups/`, then `docker compose up -d`. Make a backup first. ## Uninstall Installer: ```sh sudo securevault-server --uninstall # removes the setup, keeps the database sudo securevault-server --uninstall --delete-data --remove-mariadb # removes everything ``` Without `--delete-data` your vault stays in MariaDB, and a MariaDB that the installer installed is left listening on the machine itself only. `--remove-mariadb` removes MariaDB and its data directory only if the installer installed it and no other database is left. Backups in `/var/backups/securevault/` are never deleted. The small packages it may have installed besides MariaDB (nftables, qrencode, iproute2) stay. Docker: ```sh docker compose down # stops it; the data stays in the Docker volume docker compose down -v # deletes the vault data for good ``` Then delete the kit folder if you no longer need `.env` and `backups/`. ## Troubleshooting These happened during testing, except the two entries that say "not tested". **The app or a MariaDB client says "SSL is required, but the server does not support it".** A MariaDB command-line client of version 11.4 or newer insists on TLS by default. Add `--skip-ssl` to the client command. (The SecureVault app and agent module do not have this problem.) **The address in the connection details is wrong (a VPN address, for example).** The installer takes the address of the network card your default route uses. If that is not the address your devices reach the machine at, name it: `sudo securevault-server --address ` (listens on that address only) or add another with `--extra-host `. **"MariaDB did not come back after the restart" / the check at the end fails.** Look at `journalctl -u mariadb -n 30`. Running the installer again with other options rewrites its settings even when MariaDB is down, so a wrong `--address` or `--port` can be repaired that way. **A device cannot connect, but `securevault-server --check` is fine.** The check signs in from the server itself. From the device, test the port: `nc -z -w 5
3306` (PowerShell: `Test-NetConnection
-Port 3306`). No answer means the network in between: the device is on another network (guest Wi-Fi, mobile data without Tailscale), or a firewall. With ufw or firewalld active the installer adds its rules there; `--no-firewall` skips them. **Fedora with SELinux, and a port other than 3306.** Not tested (the tests ran in containers, where SELinux is off). SELinux lets MariaDB use port 3306 only; for another port you would need `semanage port -a -t mysqld_port_t -p tcp `. **Docker: the database container keeps restarting, and its log says "Database is uninitialized and password option is not specified".** There is no `.env` yet. Run `docker compose run --rm setup --init --address `, then `docker compose up -d`. **Docker: `.env` already exists.** `--init` never overwrites it, because the passwords in it are the ones the database was created with. Changing a password in `.env` afterwards does not change it in the database. **Docker: a client on the same computer cannot reach the address.** Use the address you gave to `--init`, not `127.0.0.1` or `localhost`: the port is published on that one address only. **Arch: "pacman could not install".** The installer uses the package lists your system already has, and stops before changing anything when they are missing or old. Run `sudo pacman -Syu` first (in a script: `--noconfirm`); it upgrades the whole system. **`sudo: securevault-server: command not found`.** Not tested: on Debian 12, Ubuntu 24.04 and Fedora 45 sudo found the command. Some systems leave `/usr/local/sbin` out of sudo's path; use the full path there: `sudo /usr/local/sbin/securevault-server`.