How to Self-Host Yopass with Docker Compose

What Is Yopass?

Yopass is a secure secret-sharing service that lets you share passwords, API keys, and sensitive text through one-time-use encrypted links. Secrets are encrypted client-side before being stored, so the server never sees plaintext data. Links auto-expire after a configurable time and are destroyed after being viewed once. It replaces services like OneTimeSecret and insecure practices like emailing passwords. Open source and available at github.com/jhaals/yopass.

Updated March 2026: Updated to Yopass 13.0.0. This release separates write and read API endpoints (/create/secret and /secret) for better access control. Docker Compose configuration unchanged.

Prerequisites

• A Linux server (Ubuntu 22.04+ recommended)
• Docker and Docker Compose installed (guide)
• 256 MB of free RAM (minimum)
• A domain name (recommended for HTTPS)

Docker Compose Configuration

Create a docker-compose.yml file:

services:
  yopass:
    image: jhaals/yopass:13.0.0
    container_name: yopass
    restart: unless-stopped
    ports:
      - "1337:1337"
    command: "--database=memcached --memcached=memcached:11211"
    depends_on:
      - memcached
    networks:
      - yopass-net

  memcached:
    image: memcached:1.6-alpine
    container_name: yopass-memcached
    restart: unless-stopped
    # Allocate 64 MB for secret storage
    command: "-m 64"
    networks:
      - yopass-net

networks:
  yopass-net:

For Redis-backed storage (persistent across restarts):

services:
  yopass:
    image: jhaals/yopass:13.0.0
    container_name: yopass
    restart: unless-stopped
    ports:
      - "1337:1337"
    command: "--database=redis --redis=redis://redis:6379/0"
    depends_on:
      - redis
    networks:
      - yopass-net

  redis:
    image: redis:7-alpine
    container_name: yopass-redis
    restart: unless-stopped
    volumes:
      - redis_data:/data
    networks:
      - yopass-net

volumes:
  redis_data:

networks:
  yopass-net:

Start the stack:

docker compose up -d

Initial Setup

1. Open http://your-server-ip:1337 in your browser
2. No account creation or setup wizard — Yopass is ready to use immediately
3. Enter a secret in the text field
4. Select an expiry time (1 hour, 1 day, 1 week)
5. Optionally set a one-time download limit
6. Click Encrypt Message to generate a shareable link
7. Send the link to the recipient — the secret is destroyed after viewing

Configuration

Command-Line Options

Configure Yopass via command-line flags in the command field:

Flag	Default	Purpose
--database	memcached	Backend: memcached or redis
--memcached	localhost:11211	Memcached connection string
--redis	redis://localhost:6379/0	Redis connection string
--port	1337	HTTP listen port
--max-length	10000	Maximum secret length in characters
--metrics-port	—	Prometheus metrics endpoint port
--tls-cert / --tls-key	—	TLS certificate and key paths

Memcached vs Redis

Feature	Memcached	Redis
Persistence	No — secrets lost on restart	Yes — survives restarts
Memory usage	Lower	Slightly higher
Secret TTL	Automatic (memcached eviction)	Automatic (Redis TTL)
Best for	Production (secrets should be ephemeral)	Development or when persistence is needed

Memcached is recommended for production — if the service restarts, secrets are gone, which is a security feature. Secrets are meant to be viewed once, not stored.

File Sharing

Yopass also supports one-time file sharing. Files are encrypted client-side and uploaded. The --max-length flag controls the maximum file size.

Reverse Proxy

For HTTPS (strongly recommended — secrets should never travel over HTTP):

• Forward Hostname: yopass
• Forward Port: 1337
• Enable SSL with Let’s Encrypt

For detailed setup, see Reverse Proxy Setup.

Backup

Yopass is designed to not need backups. Secrets are ephemeral — they’re destroyed after viewing or after the expiry time. The memcached backend intentionally does not persist data. If using Redis, you can back up the volume, but this defeats the purpose of one-time secrets.

Troubleshooting

Encrypted link returns “Secret not found”

Symptom: Recipient clicks the link but sees “Secret not found.” Fix: The secret was already viewed (one-time use) or expired. Create a new secret and share the link again. If using memcached, restarting the container also clears all secrets.

Secrets expire too quickly

Symptom: Secrets disappear before the recipient views them. Fix: Check that memcached has enough memory allocated (-m flag). If memcached runs out of memory, it evicts the oldest items. Increase the allocation: command: "-m 256".

Web UI shows a blank page

Symptom: Port 1337 responds but the page is blank. Fix: Ensure you’re accessing the correct port and that no reverse proxy is stripping the response body. Check container logs: docker logs yopass.

Resource Requirements

• RAM: ~20 MB for Yopass + 64-256 MB for memcached/Redis
• CPU: Minimal
• Disk: ~30 MB for Docker images, no persistent storage needed

Verdict

Yopass is the simplest, most secure way to share one-time secrets in a self-hosted environment. Its client-side encryption means the server never sees plaintext data, and the auto-expiry ensures secrets don’t linger. For full-featured secrets management with API access, versioning, and team features, use HashiCorp Vault or Infisical. For password sharing via encrypted pastebins, PrivateBin is also worth considering. Yopass is the right tool when you need to share a password or API key quickly and securely.

Frequently Asked Questions

How does Yopass compare to PrivateBin?

Yopass is purpose-built for one-time secret sharing — the secret is destroyed after viewing. PrivateBin is a more general encrypted pastebin that supports optional burn-after-reading, comments, syntax highlighting, and file attachments. Choose Yopass for pure one-time secrets; PrivateBin for a broader encrypted paste tool. See our PrivateBin vs Yopass comparison.

Can the server operator read my secrets?

No. Yopass encrypts secrets client-side in the browser before sending them to the server. The encryption key is part of the URL fragment (after the #), which is never sent to the server. The server only stores encrypted ciphertext that it cannot decrypt.

Can I share files through Yopass?

Yes. Yopass supports one-time file sharing alongside text secrets. Files are encrypted client-side before upload. The maximum file size is controlled by the --max-length flag. Files are destroyed after download or expiry, just like text secrets.

Should I use Memcached or Redis for Yopass?

Memcached is recommended for production. Secrets are ephemeral by design — losing them on restart is a security feature, not a bug. Use Redis only if you need secrets to survive container restarts (e.g., during development or if you have long expiry windows and frequent deployments).

Can I self-host Yopass without a domain name?

Yes, for internal use. Yopass works on http://ip:1337 for LAN sharing. However, sharing secrets over unencrypted HTTP defeats the purpose — anyone on the network can intercept the link. For any use beyond a trusted local network, set up HTTPS with a domain and reverse proxy.

Does Yopass support multiple users or authentication?

No. Yopass has no user accounts, authentication, or access control. Anyone with access to the URL can create secrets. If you need to restrict who can create secrets, place Yopass behind a reverse proxy with authentication (e.g., Authelia or HTTP basic auth).

Related

• PrivateBin vs Yopass: Which Should You Self-Host?
• Best Self-Hosted Secrets Management Tools
• HashiCorp Vault vs Infisical
• How to Self-Host HashiCorp Vault
• How to Self-Host Infisical
• How to Self-Host PrivateBin
• Docker Compose Basics
• Reverse Proxy Setup