Documentation

Welcome to the official giovium documentation. Here you can find comprehensive guides to installing and configuring your self-hosted giovium server.

Client Setup

giovium is designed to be immediately accessible without complex configuration. Simply download the application for your operating system (iOS, Android, macOS, Windows, Linux) and follow the on-screen instructions.

During your first launch, you will establish a master password to encrypt your local vault. Do not forget it, as it is fully unrecoverable.

Server Connection Settings

• Address: Upon launch, the client will ask for your server's IP address (local network or public internet) or a fully qualified domain name.
• Port & Protocol: You can use any port you like. If you specify port 443, the client will route through HTTPS. If you use any other port, it will route through standard HTTP. Regardless of the protocol, the giovium connection is completely encrypted internally.
• Reverse Proxies: Deploying on a domain over port 443 behind a reverse proxy (like NGINX) is useful if you want to cleanly reach a subdomain (e.g., giovium.yourdomain.com) on a port already in use. Note: if you use a reverse proxy, you must supply a valid TLS certificate. If you do not use a reverse proxy or certificate and run on an alternate port, the app will still enforce its own strict encryption.
• Public Key (Optional): The public key (in hex format) is used during your initial setup to cryptographically verify that the server you are talking to is the exact one you deployed. While optional, it is highly recommended. You can find this key in the /data/publicKey.txt file directly on your server immediately after its first launch.

Server Deployment

Quick Start (Docker)

The fastest way to deploy giovium is via Docker, ensuring a clean containerized instance.

docker run -p 8000:8000 xgiovio/giovium-server

Quick Start (Server Binary)

Alternatively, you can directly run the native server executable specifically compiled for your operating system.

./giovium-server -p 8000 -h 0.0.0.0

Configuration Options

• Port: Use -p or --port to specify the exposed port (default 8000).
• Interface: Use -h or --host to specify the bind interface (default 0.0.0.0).

Data Persistence

Server data is saved in the /data folder. To make your data persistent so it doesn't disappear when a container stops or gets deleted, you need to use a Docker Volume. Volumes are managed by Docker and safely stored outside the container's lifecycle.

Reconnection & Device Recovery

Because giovium synchronizes across your hardware, your data remains safe on your other devices (desktop, mobile, or alternative servers) even if your primary server goes down.

Replacing or Adding a Server

If you need to replace a downed server or attach an additional one, simply remove the old server profile from your app's Settings and add the new one. This new server automatically binds to your app and immediately syncs with all other devices sharing the same vault.

Recovering a Lost Device

If you lose a device and need to set up a brand new client connected to your existing server, you'll go through a strict security handshake:

1. On the first screen of the new app, enter your server connection details.
2. Because your server already contains data, the app will display a unique security token.
3. Access your server manually and create a file named token.txt inside the /data folder. Insert the provided token into this file.
4. Return to the app, enter your Master Password, and click Import. The app will send the token to the server. Once the server verifies the token, the app will securely download your encrypted vault and use your Master Password to restore access.

Security Rationale: A newly installed app is completely unknown to your server. The token verification acts as a primary defense preventing your server from transmitting your encrypted vault to an unauthorized stranger. Furthermore, even if this token verification were somehow bypassed, your vault and data remain completely inaccessible without your Master Password.

Network & Reverse Proxy

The server runs on HTTP. It doesn't strictly need to be behind SSL, but if you prefer, you can easily host it behind a reverse proxy like NGINX.

Once paired, all communications are always encrypted and signed internally between the server and clients for maximum security. Even if you host giovium on a public server without any reverse proxy, your data remains completely safe.