Deploying Shhh

Introduction

Shhh is a secure, self-hosted secret sharing application designed for safely transmitting sensitive information like passwords, API keys, and credentials. Instead of sending secrets through insecure channels like email or chat, Shhh encrypts your data and generates a one-time link that automatically expires after being viewed or after a set time period.

Built with Python and Flask, Shhh provides a simple web interface for creating and retrieving secrets. The application uses strong encryption (AES-256) and ensures that secrets are stored encrypted at rest, with the decryption key embedded in the shareable URL rather than stored on the server.

Key highlights of Shhh:

• End-to-End Encryption: Secrets encrypted with AES-256 before storage
• One-Time Links: Secrets automatically delete after viewing
• Time-Based Expiration: Set secrets to expire after a specified duration
• No Account Required: Share secrets without registration
• Passphrase Protection: Add an additional layer of security
• Read Receipts: Know when a secret has been accessed
• Simple API: Programmatic secret creation
• Minimal Footprint: Lightweight Python application
• 100% Open Source: Licensed under MIT

This guide walks through deploying Shhh on Klutch.sh using Docker, configuring security settings, and sharing secrets safely.

Why Deploy Shhh on Klutch.sh

Deploying Shhh on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh handles container orchestration without complex Python setup.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, essential for secure secret sharing.

Persistent Storage: Attach volumes for the database that survives restarts.

Custom Domains: Use your own domain for trustworthy secret sharing URLs.

Always-On Availability: Your secret sharing service remains accessible when you need it.

Prerequisites

Before deploying Shhh on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your Shhh configuration
• Basic familiarity with Docker and containerization concepts

Preparing Your Repository

Create a GitHub repository with your Shhh configuration.

Repository Structure

shhh-deploy/
├── Dockerfile
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM smallwat3r/shhh:latest

# Environment variables
ENV SHHH_HOST=0.0.0.0
ENV SHHH_PORT=5000
ENV SHHH_ENV=production
ENV SHHH_SECRET_KEY=${SHHH_SECRET_KEY}

# Database configuration
ENV SHHH_DB_URI=${SHHH_DB_URI:-sqlite:////data/shhh.db}

# Application settings
ENV SHHH_DEFAULT_EXPIRATION=${SHHH_DEFAULT_EXPIRATION:-3d}
ENV SHHH_MAX_EXPIRATION=${SHHH_MAX_EXPIRATION:-7d}
ENV SHHH_MAX_SECRET_LENGTH=${SHHH_MAX_SECRET_LENGTH:-5000}

# Create data directory
RUN mkdir -p /data

# Expose the web interface port
EXPOSE 5000

Environment Variables Reference

Variable	Required	Default	Description
SHHH_SECRET_KEY	Yes	-	Flask secret key for sessions
SHHH_DB_URI	No	sqlite:///shhh.db	Database connection URI
SHHH_DEFAULT_EXPIRATION	No	3d	Default secret expiration time
SHHH_MAX_EXPIRATION	No	7d	Maximum allowed expiration time
SHHH_MAX_SECRET_LENGTH	No	5000	Maximum secret length in characters
SHHH_HOST	No	0.0.0.0	Bind address
SHHH_PORT	No	5000	Application port
SHHH_ENV	No	production	Environment mode

Deploying Shhh on Klutch.sh

Generate Secret Key

Generate a secure secret key for Flask:

python3 -c "import secrets; print(secrets.token_hex(32))"

Or:

openssl rand -hex 32

Push Your Repository to GitHub

Initialize and push your repository:

git init
git add Dockerfile .dockerignore
git commit -m "Initial Shhh deployment configuration"
git remote add origin https://github.com/yourusername/shhh-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project with a descriptive name like “shhh” or “secrets”.

Create a New App

Within your project, create a new app. Connect your GitHub account and select your Shhh repository.

Configure HTTP Traffic

In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 5000

Set Environment Variables

Add the following environment variables:

Variable	Value
SHHH_SECRET_KEY	Your generated secret key
SHHH_DEFAULT_EXPIRATION	3d
SHHH_MAX_EXPIRATION	7d

Attach Persistent Volumes

Add the following volume:

Mount Path	Recommended Size	Purpose
/data	1 GB	SQLite database storage

Deploy Your Application

Click Deploy to start the build process.

Access Shhh

Once deployment completes, access your Shhh instance at https://your-app-name.klutch.sh.

Using Shhh

Creating a Secret

1. Navigate to your Shhh instance
2. Enter your secret in the text area
3. Configure options:
   • Expiration time
   • Optional passphrase
   • Number of allowed reads (1 = one-time)
4. Click Encrypt & Share
5. Copy the generated link

Retrieving a Secret

1. Open the shared link
2. Enter passphrase if required
3. Click Decrypt
4. View the secret
5. The secret is deleted after viewing (if one-time)

Security Best Practices

• Share links securely: Use a different channel for the link than you would for the secret itself
• Use passphrases: Add a passphrase and share it separately from the link
• Set short expirations: Use the shortest practical expiration time
• One-time links: Enable one-time read for highly sensitive data

API Usage

Shhh provides a simple API for programmatic secret sharing:

Create a Secret

curl -X POST https://your-app-name.klutch.sh/api/c \
  -H "Content-Type: application/json" \
  -d '{
    "secret": "my-secret-password",
    "passphrase": "optional-passphrase",
    "days": 1,
    "tries": 1
  }'

Read a Secret

curl -X POST https://your-app-name.klutch.sh/api/r \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "secret-slug-from-url",
    "passphrase": "optional-passphrase"
  }'

Advanced Configuration

Using PostgreSQL

For higher availability, use PostgreSQL instead of SQLite:

SHHH_DB_URI=postgresql://user:password@host:5432/shhh

Custom Expiration Options

Configure available expiration options:

Suffix	Meaning
m	Minutes
h	Hours
d	Days

Examples: 30m, 12h, 3d, 7d

Rate Limiting

Add rate limiting in a reverse proxy or configure additional middleware to prevent abuse.

Troubleshooting

Secret Link Not Working

Symptoms: Link returns “not found” or decryption error.

Solutions:

• Verify the complete URL was copied (including the hash fragment)
• Check if the secret has expired
• Confirm the secret hasn’t been read already (one-time)
• Ensure the passphrase is correct

Database Errors

Symptoms: Application fails to save or retrieve secrets.

Solutions:

• Verify persistent volume is mounted
• Check database file permissions
• Ensure SHHH_DB_URI is correct
• Review application logs

High Memory Usage

Symptoms: Application crashes or runs slowly.

Solutions:

• Check for expired secrets accumulating (should auto-clean)
• Review SHHH_MAX_SECRET_LENGTH setting
• Increase container memory allocation

Additional Resources

• Shhh GitHub Repository
• Shhh Demo Instance

Conclusion

Deploying Shhh on Klutch.sh gives you a secure, private way to share sensitive information. With end-to-end encryption, automatic expiration, and one-time links, Shhh ensures that passwords and secrets don’t linger in email inboxes or chat histories where they can be compromised.