Sponsor Project
Ciphra Logo
Ciphra
Developer Documentation

Building Ciphra

The complete guide to self-hosting, compiling, and deploying your own end-to-end encrypted document infrastructure.

Prerequisites

You will need the following installed before starting:

Step 1 — Clone and Install

First, clone the repository to your local machine:

git clone .../Ciphra.git

Navigate into the project directory:

cd Ciphra

Install all the required dependencies:

npm install

Step 2 — Set up Convex (Development)

In Terminal 1, start the Convex dev server:

npx convex dev

Setup Process

  • 1.You will be prompted to log in to Convex.
  • 2.Select Create a new project and name it ciphra.
  • 3.Convex automatically creates .env.local in your project root.

Step 3 — Run in Development

In Terminal 2, start the Tauri dev build:

npx tauri dev

🚀 The app window will open. Create accounts, add documents and images — everything is fully functional in development mode.

Step 4 — Get Production Keys

To prepare your production environment, go to your Convex Dashboard and open your ciphra project. Follow these exact steps:

  • 1
    Change from the Development tab to the Production tab (top left).
  • 2
    Go to Settings > General.
  • 3
    Click Generate a production key. Add a name (e.g., "production") and click Create.
  • 4
    Copy your production key and save it somewhere safe. You will need it later for the Windows/Linux build step.
    Example: prod:f**********************************
  • 5
    Finally, copy your Convex URL and Site URL from the box at the top right of the dashboard.

Now, create a .env.production file in your project root and paste those URLs:

VITE_CONVEX_URL="...conve..."
VITE_CONVEX_SITE_URL="...conv.."

Step 5 — Generate Signing Keys

Tauri requires all distributed builds to be cryptographically signed. Generate your key pair by running:

npx tauri signer generate

Key Generation Process

  • You will be prompted to enter a password. Make sure to choose a strong one.
  • The CLI will output a Public Key and a Private Key.
  • Important: Save your password, public key, and private key somewhere very safe (like a password manager). You will need them for future updates.

Once you have generated and saved your keys, create an .env file in your project root and add them:

...PRIVATE_KEY="your_key"
...PASSWORD="your_password"

Environment File Summary

After completing the setup, you should have exactly 3 environment files in the root of your project. Here is a summary to ensure everything is configured correctly:

File.env.local
EnvironmentDevelopment

Connects your app to the Convex development database.

Auto-generated by Convex CLI.
File.env.production
EnvironmentProduction

Connects your app to the live Convex production database.

Manually created by you in Step 4.
File.env
EnvironmentBuild / Security

Stores cryptographic keys for signing desktop app releases.

Must remain completely private.

Step 6 — Build Prerequisites

Before compiling the native desktop applications, ensure your operating system has the necessary build tools. While Node.js and Rust are required across all platforms, Linux needs a few extra packages.

🪟 Windows

Windows builds are straightforward. As long as you have the Rust toolchain (which includes the Visual Studio C++ Build Tools) and Node.js installed, no extra system libraries are needed. You are ready to build!

🐧 Linux

Linux requires specific WebKit and GTK development packages to render the Tauri webview correctly. See the exact terminal commands below for your specific distribution.

Ubuntu / Debian
sudo apt update
sudo apt install libwebkit2gtk...
Fedora / RHEL
sudo dnf install webkit2gtk...

Step 7 — Windows Build

Now it's time to compile the desktop application for Windows.

ℹ️
Important Note: The following commands use the $env: syntax. This means you must run them in PowerShell. Open PowerShell in your project root before continuing.

1. Deploy Convex to Production

First, set your production deploy key (obtained in Step 4):

$env:CONVEX_DEPL..."

Next, push your schema and backend functions to the live database:

npx convex deploy

2. Set Signing Keys

Load your private key (generated in Step 5) into the environment:

$env:...PRIVATE_KEY="you.."

Load the password for your private key:

$env:...PASSWORD="your_pa.."

3. Compile the Application

Run the final Tauri build command. This step will take a few minutes as it compiles the Rust binaries and webview bindings.

npx tauri build

📦 Build Output

src-tauri/target/release/bundle/
  • MSImsi/Ciphra_x.x.x_x64_en-US.msi
    Windows Installer
  • NSISnsis/Ciphra_x.x.x_x64-setup.exe
    Standalone Setup Executable

Step 8 — Linux Build

Finally, compile the native desktop application for Linux distributions.

🐧
Important Note: These commands use standard Bash export syntax. Also, if you already deployed your Convex backend during the Windows build, you can skip Step 1 here.

1. Deploy Convex (If not done already)

Set your production deploy key and push your backend schema:

export CONVEX_..."
npx convex deploy

2. Set Signing Keys

Export your private key and password into the active terminal session:

export ...PRIVATE...."
export ...PASSWO..."

3. Compile the Application

Run the final Tauri build. This will generate AppImage, DEB, and RPM packages.

npx tauri build

Troubleshooting: If you encounter AppImage packaging errors, run this alternative command instead:

NO_STRIP=1 ... npm run

📦 Build Output

src-tauri/target/release/bundle/
  • APPIMAGEappimage/Ciphra_x.x.x_amd64.AppImage
    Universal Linux App
  • DEBdeb/Ciphra_x.x.x_amd64.deb
    Ubuntu / Debian
  • RPMrpm/Ciphra-x.x.x-1.x86_64.rpm
    Fedora / openSUSE