Obscura Server

Obscura Server is a minimalist, secure relay server for the Signal Protocol. It facilitates end-to-end encrypted asynchronous messaging while knowing nothing about the content of the messages.

Features

• Zero-Knowledge Architecture: The server stores opaque encrypted blobs. It cannot read message content.
• Signal Protocol Support: Uses PreKeys (Identity, Signed, One-Time) to enable X3DH key exchanges.
• Asynchronous Delivery: Stores encrypted messages until the recipient comes online to fetch them.
• Encrypted Attachments: Supports secure file uploads via S3-compatible storage with automated expiry.
• Strict Privacy Limits: Automatic garbage collection of old messages and global inbox limits to prevent metadata buildup.
• OpenTelemetry Native: Built-in support for Traces, Metrics, and Structured Logging via OTLP.
• Container Native: Built with Docker in mind for easy deployment.
• Configurable: Fully configurable via command-line flags or environment variables.

Configuration

Obscura Server can be configured using either command-line options or by setting corresponding environment variables. Command-line options take precedence over environment variables.

General Configuration

Server Configuration

Rate Limiting

Storage Configuration (Attachments)

Messaging & Notifications

WebSocket Configuration

Telemetry & Health

Example

# Using Flags
./obscura-server \
  --database-url postgres://user:pass@localhost/db \
  --jwt-secret my_secret \
  --storage-bucket my-attachments \
  --server-port 8080

# Using Environment Variables
export OBSCURA_DATABASE_URL=postgres://user:pass@localhost/db
export OBSCURA_JWT_SECRET=my_secret
export OBSCURA_STORAGE_BUCKET=my-attachments
./obscura-server

Docker

A Dockerfile is included for easy deployment.

Build and Run

1. Build the image:

   docker build -t obscura-server .
   

2. Run with Docker:

   docker build -t obscura-server .
   docker run -d \
     -p 3000:3000 \
     -p 9090:9090 \
     -e OBSCURA_DATABASE_URL="postgres://user:pass@host.docker.internal:5432/obscura" \
     -e OBSCURA_JWT_SECRET="your_secret_key" \
     -e OBSCURA_STORAGE_BUCKET="obscura-attachments" \
     obscura-server
   

Docker Compose

A docker-compose.yml is provided for a complete local stack (Postgres + Server):

docker compose up -d

Development

Prerequisites

• Rust 1.83+
• PostgreSQL 16+
• protoc (Protocol Buffers compiler)

Running Locally

1. Start Postgres and MinIO:

   docker compose up -d db minio
   

2. Run the server:

   export OBSCURA_DATABASE_URL=postgres://user:password@localhost/signal_server
   export OBSCURA_JWT_SECRET=test
   export OBSCURA_STORAGE_BUCKET=test
   cargo run
   

   Migrations are applied automatically on startup.

Testing

cargo test

Releasing

Releases are managed via GitHub Actions.

1. Go to the Actions tab in the GitHub repository.
2. Select the Bump Version & Tag workflow on the left.
3. Click Run workflow.
4. Select the Bump Type from the dropdown (patch, minor, or major).
5. Click Run workflow.

The system will automatically:

1. Bump the version in Cargo.toml based on your selection.
2. Commit and Tag the release.
3. Trigger the Publish Release workflow to build and publish artifacts to Crates.io and GHCR.

API Documentation

• REST API: Defined in openapi.yaml.
• WebSocket: Available at /v1/gateway. Expects Protobuf messages defined in proto/obscura/v1/obscura.proto.

License

Copyright (c) 2026 Nolan Cooper

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.