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 February 2026: Verified with latest Docker images and configurations.

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:11.18.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:11.18.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.

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