yopass Documentation

The secret_id in the webhook payload is a deterministic fingerprint. To map a webhook event back to a specific secret, compute the first 12 hex characters of the SHA-256 hash of the raw secret ID (the path segment of the share link).

Formula: secret_id = first 12 hex characters of SHA-256(raw secret ID)

Example (Bash):

printf '%s' '8GjMyrJDkLwmnvKg9N1bzS' | sha256sum | cut -c1-12

Example (Python):

import hashlib
fingerprint = hashlib.sha256(raw_id.encode()).hexdigest()[:12]

Before deploying the CDK stack, you must store the yopass license key (JWT) in the AWS SSM Parameter Store. The stack expects the key to be located at the path /yopass/license-key.

aws ssm put-parameter --name /yopass/license-key --type String --value '<jwt>'

To run Yopass with a Redis storage backend, use the following Docker Compose configuration.

Prerequisites:

• Docker and Docker Compose (v2+)
• Port 1337 available on your machine

1. Create a docker-compose.yml file with the following content:

services:
  yopass:
    image: jhaals/yopass:latest
    ports:
      - "1337:1337"
    environment:
      DATABASE: redis
      REDIS: redis://redis:6379/0
    depends_on:
      - redis

  redis:
    image: redis:7-alpine

2. Start the services:

docker compose up -d

3. Access the application at http://localhost:1337.

Install the yopass CLI using Go. Note that installations protected with OpenID Connect are not supported by the CLI.

go install github.com/jhaals/yopass/cmd/yopass@latest

Replace the default Yopass logo in the navbar and browser tab using the --logo-url flag (or LOGO_URL environment variable). This requires a valid --license-key.

Image Requirements:

• Format: SVG (recommended), PNG, JPEG, or WebP.
• Shape: Square (displayed at 32×32 px).
• Resolution: At least 64×64 px for Retina displays.
• File size: Keep below 100 KB.

Usage Modes:

• Relative Path: e.g., /mylogo.png. If using Docker, copy the file into the frontend's /public directory.
• External URL: e.g., https://cdn.example.com/logo.svg. The server automatically updates the img-src Content Security Policy (CSP) to allow this origin.

FROM jhaals/yopass:latest
COPY mylogo.png /public/mylogo.png

docker build -t yopass-custom .
docker run -p 1337:1337 yopass-custom \
  --license-key your-license-key \
  --logo-url /mylogo.png

You can serve Yopass over HTTPS directly by providing paths to a PEM-encoded TLS certificate and private key using the --tls-cert and --tls-key flags. Yopass enforces a minimum TLS version of TLS 1.2. Note that both flags must be provided together, or the server will fail to start.

Example: Using Let's Encrypt certificates

yopass-server \
  --tls-cert /etc/letsencrypt/live/yopass.example.com/fullchain.pem \
  --tls-key  /etc/letsencrypt/live/yopass.example.com/privkey.pem

Example: Using self-signed certificates (Development only)

openssl req -x509 -nodes -newkey rsa:4096 \
  -keyout tls.key -out tls.crt \
  -days 365 -subj "/CN=localhost"

yopass-server --tls-cert tls.crt --tls-key tls.key

yopass-server \
  --tls-cert /etc/ssl/yopass/tls.crt \
  --tls-key  /etc/ssl/yopass/tls.key

Add a scrape job to your prometheus.yml. If running in Docker, use the container name as the target.

scrape_configs:
  - job_name: yopass
    static_configs:
      - targets: ["yopass-host:9090"]

The default file storage backend stores files alongside text secrets in Memcached or Redis. No extra configuration is required for this mode.

Limitations:

• Memcached: Has a default item size limit of ~1 MB. Files larger than this will fail to store.
• Redis: While it has a higher limit, it is not ideal for large binary objects.
• A warning is printed at startup if --max-file-size exceeds 1 MB without a dedicated file store (disk or S3) configured.

yopass-server  # file-store defaults to the database backend

The metrics endpoint has no authentication. You should restrict access at the network level.

Option 1: Firewall (ufw) Allow only specific IP ranges to access port 9090 and deny public access.

Option 2: Nginx Basic Auth Place Nginx in front of the metrics port to require authentication.

Option 3: Docker Internal Network (Recommended) In Docker Compose, do not map the metrics port to the host. Instead, let Prometheus scrape the container via the internal Docker network by omitting the ports: entry for the Yopass service.

# Expose to internal network only — no host port mapping
yopass:
  environment:
    METRICS_PORT: "9090"
  # No "ports:" entry for 9090

Use the --max-file-size flag to set the maximum allowed upload size. It accepts human-readable suffixes like KB, MB, and GB.

Important: Without a valid --license-key, file size is capped at 1 MB regardless of your configuration. A warning will be logged when this cap is applied.

--max-file-size 10KB
--max-file-size 512KB
--max-file-size 10MB
--max-file-size 1.5GB

Use the provided Kubernetes manifest for a minimal setup. Note that you must configure TLS before using this in a production environment.

kubectl apply -f deploy/yopass-k8.yaml
kubectl port-forward service/yopass 1337:1337