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 and you will need a reverse proxy with a valid certificate. 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 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 on port 443, you must supply a valid TLS certificate.
• 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.

Client Features & Capabilities

The giovium client offers an extensive suite of tools for managing your data precisely the way you want:

• Unlimited Items & Dynamic Fields: Create an unlimited number of items. For each item, you can dynamically add standard text fields, text areas for longer notes, concealed passwords, and file attachments.
• Built-in Tools: Every field supports show/hide toggles and one-click copy buttons. The client also features a built-in application password generator.
• Advanced TOTP Support: Add Time-based One-Time Passwords (TOTP) by manually entering the secret string or by directly scanning a QR code with your device's camera.
• File Management: Securely attach files to any item. You can download attached files and verify their cryptographic checksums to ensure perfect file integrity.
• Version History: Data is always appended and pushed, never permanently removed. You can seamlessly browse and restore past versions of any item.
• Double Encryption: During creation, items can be assigned an additional, personal password. This provides a secondary layer of protection that is completely independent of your main master password.
• Item Visibility & Hiding: giovium versions all your data natively. If you no longer want to see an item, simply open its settings and disable its visibility. This immediately filters it out from your regular searches. To retrieve or search for it again, go to the application settings and enable show hidden items, allowing you to search across everything. You can also select show hidden items only to search exclusively within your hidden entries.
• Security & Device Settings: Switch between Light and Dark themes, manage multiple server connections, enable Face ID or biometric encryption, and enforce device owner authentication (which verifies the actual physical owner of the device, even if someone else knows the master password).
• Mobile Screen Protection: The mobile applications include strict anti-espionage features that actively protect against screenshots and screen recording.
• Dynamic Search & Tagging: Since all item contents are strictly encrypted and only decrypted upon access, searching within the actual content is intentionally disabled for your privacy. To ensure fast retrieval, you can add a descriptive name and comma-separated tags to every item. When using the search bar, you can input multiple comma-separated keywords; the search engine will extract each query and instantly filter items that match the given names or tags. Always add clear names and relevant keywords to your items for the best search experience.

Importing & Exporting

You can seamlessly import and export your unencrypted vault data in bulk using the standard giovium format. When performing an import or export, you must select the specific .giovium file on your disk. Any file attachments referenced during the import process must be located at a path relative to the selected .giovium file. Please check the format documentation for more details about how to structure your items. Note that items protected by a second password cannot be processed in bulk.

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).

Where are my encrypted files stored?

Your encrypted database and file attachments are stored locally depending on your platform:

Client Vault Storage

• Mobile (iOS & Android): Stored securely in the app's Document directory. On iOS, they are also directly accessible via the native Files app and available for iCloud backup.
• Desktop (Windows): AppData/giovium/vault
• Desktop (macOS): Library/Application Support/giovium/vault
• Desktop (Linux): Local application folders under your home directory, then giovium/vault.

Server Storage & Persistence

Server data is securely saved in the /data folder next to the executable. To make your server data persistent so it doesn't disappear when a Docker container stops or gets deleted, you must map a Docker Volume to this path. Volumes are managed by Docker and safely store your data outside the container's lifecycle on your host OS.

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.

App Crashes & Local Backups

If the app ever crashes or if you simply want to manually secure your data, you can directly access your encrypted vault files. On iOS, your data is accessible via the native Files app; you can copy your vault to safely back it up or move it to another device whenever you want. On desktop platforms, your encrypted vault is securely stored in standard application support folders. You always retain full, independent control to manually back up and restore your files without relying on the app itself.

Replacing or Adding a Server

If you need to add an additional server to sync, simply set up the new server, go into the app's settings, and add the new server. You can add a new, empty server or an already synced server. Note that unlike the first sync, when adding a server from settings, you can only add a brand new server or a server that is already synced with the same vault.

Furthermore, if you need to move your server data to another machine, it is completely safe and possible. Simply shut down your existing server, copy the /data folder to the new server, and start the new server using that copied data.

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 & Hosting Options

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.

Self-Hosting at Home

If you want to self-host giovium at home, you can connect to your server using its local IP address and port. If you need to access it from outside your home network (behind a NAT), simply configure your router to port-forward external traffic to the internal IP and port of your server. If your home IP address is dynamic, you can use a DDNS (Dynamic DNS) service to maintain a persistent address.

Cloud VPS Hosting

Alternatively, you can host it on your own hardware or rent a mini VPS for just 2 to 3 Euros per month. You can then connect directly to the server's public IP address over the internet, or simply map a custom domain name to it.

If you need any information or assistance with your configuration, feel free to contact me using the details provided in the footer below. I will gladly help you get set up!