Self-Host Wastebin with Docker and Localtonet

What you are self-hosting

Wastebin is a minimal pastebin application backed by SQLite. It runs as a single server process and provides a browser interface for creating and reading text pastes. The application compresses stored pastes with zstd and supports syntax highlighting for more than 170 languages through syntect. Pastes using an md or markdown extension can also be displayed as rendered Markdown.

Its Markdown renderer supports GitHub-flavored features such as tables, task lists, admonitions, and highlighted fenced code blocks. Raw HTML in Markdown is sanitized. Safe elements such as <details>, <summary>, and <kbd> can be retained, while scripts, inline event handlers, and javascript: URLs are removed. The Content Security Policy permits external images on rendered Markdown routes, while other routes retain the stricter default policy.

Wastebin also supports expiration, deletion after reading, deletion by an anonymous owner, QR-code display, nine light and dark themes, and password-protected encrypted entries. Paste encryption uses ChaCha20Poly1305, while user-provided passwords used for encryption are hashed with Argon2. These paste-level capabilities are useful, but they must not be confused with application access control. Wastebin does not provide user authentication, user accounts, or administrator functionality.

What Wastebin intentionally does not include

The project identifies user authentication, administrator functionality, arbitrary file uploads, and comprehensive denial-of-service mitigations as non-features. This matters when deciding who should be able to reach the service. Anyone who can reach an exposed instance can potentially submit requests and create pastes unless another component enforces access restrictions before traffic reaches Wastebin.

Why use Docker Compose for this installation?

Wastebin can be installed in several ways, but Docker Compose makes the service definition, port publication, restart policy, database path, and persistent host directory visible in one file. It also makes it straightforward to stop and recreate the container without replacing the SQLite database.

This guide uses the published container image and Docker Compose. It does not require a Rust toolchain, a source checkout, or a locally built image.

Prerequisites and deployment plan

Prepare a machine that can run Docker containers and that has enough persistent disk space for the pastes you intend to retain. The extracted project documentation does not state a minimum CPU, memory, or storage allocation, so we do not invent one here. Actual storage use depends on the number, size, compression ratio, and retention period of your pastes.

You need the following:

• Docker Engine or Docker Desktop with the docker compose command available.
• A working directory where the Compose file and persistent data directory will be stored.
• Permission to create directories and adjust their ownership or write permissions.
• TCP port 8088 available on the host, unless you deliberately select another host-side port.
• A web browser for functional testing.
• For remote access, the Localtonet client running on the Wastebin host or on another device that can reach the published host port.

Understand the network path before installing

Wastebin listens on 0.0.0.0:8088 by default inside its runtime environment. The official Compose example publishes host port 8088 to container port 8088. With the mapping 8088:8088, Docker normally publishes the service on the host's available interfaces, subject to the host operating system, Docker networking mode, and firewall configuration.

If the Localtonet client runs on the same host, you can restrict the Docker publication to loopback by changing the port mapping to 127.0.0.1:8088:8088. The local browser and Localtonet client can then use 127.0.0.1:8088, while other devices on the LAN cannot connect directly through the host's LAN address. This is a Docker port-publication choice, not a Wastebin setting.

If the Localtonet client runs on a separate machine, loopback-only publication will not work because 127.0.0.1 always refers to the machine making the connection. In that topology, publish Wastebin on an interface reachable from the Localtonet client and use host firewall rules to restrict access to the required source.

Install Wastebin with Docker Compose

The installation below follows the project's documented Compose configuration: it uses the published quxfoo/wastebin:latest image, sets the database path to /data/state.db, publishes port 8088, mounts ./data at /data, and uses an automatic restart policy.

Create the directories

mkdir wastebin
cd wastebin
mkdir data

On a native Linux host, check the directory's numeric ownership and permissions:

ls -ldn data

The project specifically requires ./data to be writable by user ID 10001. If it is not writable, adjust ownership or permissions using the administrative method appropriate for your host. For example, changing the owner to numeric user ID 10001 is one possible Linux approach:

sudo chown 10001 data

Do not make the directory world-writable merely to silence a permission error. It contains the SQLite database and should be accessible only to the accounts and services that need it. On Docker Desktop, host-to-container permission behavior differs from native Linux, so first try the bind mount and inspect the logs before making broad permission changes.

Create compose.yaml

services:
  wastebin:
    restart: always
    environment:
      - WASTEBIN_DATABASE_PATH=/data/state.db
    ports:
      - "8088:8088"
    volumes:
      - "./data:/data"
    image: "quxfoo/wastebin:latest"

If Docker and the Localtonet client are on the same machine and you do not need direct LAN access, replace the port entry with a loopback-only publication:

ports:
  - "127.0.0.1:8088:8088"

Keep only one of those mappings. Do not include both unless you have a specific networking reason to publish the same service twice.

Validate and start the service

docker compose config
docker compose up -d
docker compose ps
docker compose logs wastebin

The configuration command should print the normalized Compose model without reporting a parsing error. The status command should show the Wastebin service running. Startup logs should not show an inability to create or migrate the database, and they should not report that port 8088 is already allocated.

Configure storage, limits, cookies, and presentation

The minimal Compose file is sufficient to start a persistent instance, but Wastebin exposes environment variables for important runtime behavior. Add only settings you understand, validate the resulting Compose file, and recreate the service after making a change.

Database persistence

Wastebin's application default is an in-memory database. An in-memory database disappears when the process exits, so it is not suitable when pastes must survive a container restart. The Compose file deliberately sets:

WASTEBIN_DATABASE_PATH=/data/state.db

The bind mount maps the host's ./data directory to /data in the container. As a result, state.db is created on persistent host storage rather than only in the container's writable layer. Recreating the container does not remove that host file.

Persistence is not the same as backup. File deletion, filesystem corruption, operator error, failed storage, or a damaged SQLite database can still cause data loss. Back up the host data directory using a process appropriate for SQLite. Coordinate backups to avoid copying a database in an inconsistent state while it is being modified. The Wastebin evidence supplied for this article does not prescribe a backup command or online-backup procedure, so test your chosen method and its restoration behavior before relying on it.

Signing key and owner cookies

If WASTEBIN_SIGNING_KEY is not configured, Wastebin generates a random signing key at startup. That means cookies created before a restart become invalid. In particular, paste creators can lose the cookie-based ability to delete pastes they anonymously created.

For consistent cookie behavior across restarts, configure a stable, secret signing key of at least 64 bytes. Generate and store it through your normal secret-management process. Do not paste a real signing key into documentation, source control, container logs, chat messages, or a publicly shared Compose file.

Password salt

The documented default for WASTEBIN_PASSWORD_SALT is somesalt. For an installation where password-protected pastes will be used, replace that public default with a deployment-specific secret value. Treat it as sensitive configuration and decide how it will be preserved during migration and disaster recovery.

Request size and timeout

The default maximum POST body is 1048576 bytes, or 1 MB. If a paste submission exceeds that limit, increasing a reverse proxy's request limit alone will not change Wastebin's own application limit. Conversely, increasing Wastebin's limit does not automatically change limits in a proxy placed in front of it.

The default HTTP processing timeout is five seconds. Raising body-size or timeout limits increases the resources that individual requests may consume. Any change should be considered alongside reverse-proxy limits, expected users, available resources, and abuse controls.

Base URL for QR codes

Wastebin can display a paste URL as a QR code. WASTEBIN_BASE_URL determines the base URL used for that feature. After Localtonet assigns the public HTTPS address, you can set this variable to that exact address if you want QR codes to point to the remote URL rather than a local address.

If the public address later changes, update the base URL and recreate the Wastebin container. Do not guess the Localtonet hostname before a tunnel has assigned it.

Verify the local installation before tunneling it

Remote-access troubleshooting is much easier when the application has already passed local checks. Verify the container, network port, browser interface, paste creation, and persistence before opening the Localtonet dashboard.

docker compose ps
docker compose logs wastebin
docker compose stop
docker compose start

You can also make a basic HTTP GET request from the Docker host:

curl http://127.0.0.1:8088/

This is only a reachability check. Wastebin's browser workflow provides the more useful functional test because it confirms that a paste can be created, retrieved, rendered, and retained.

Useful browser controls

When viewing a paste, Wastebin supports keyboard shortcuts. Press r for the raw paste, n for the index page, y to copy the current URL, c to copy the content, q to show a QR code, p for formatted output, w to toggle line wrapping, and m to toggle rendered Markdown. Press ? to display the available keybindings. The paste editor also accepts Ctrl+S to submit text.

Routine operation, updates, and recovery planning

Start, stop, and inspect Wastebin

docker compose up -d
docker compose stop
docker compose start
docker compose ps
docker compose logs wastebin

Stopping the service leaves the container and bind-mounted database in place. Starting it resumes the same service. The configured restart: always policy instructs Docker to restart the container according to that policy, but it does not repair an invalid configuration, a non-writable database directory, or a host port conflict.

Apply configuration changes

After editing compose.yaml, validate it and ask Compose to reconcile the running service:

docker compose config
docker compose up -d

Some environment changes require the container to be recreated before the process receives them. Check the service status and logs after every configuration change, then repeat the browser and persistence tests if the change affects storage, networking, cookies, expiration, or request handling.

Update the container image

If you use latest, updating is an explicit operational action. Pull the configured image and recreate the service:

docker compose pull
docker compose up -d
docker compose ps
docker compose logs wastebin

Back up the persistent data before an update. Review the target release and test restoration before depending on the updated instance. Do not remove the old backup until you have verified paste creation, retrieval, expiration behavior, owner actions, and restart persistence.

Pin a tested version

A pinned image tag makes deployments more predictable by preventing a later pull from silently selecting a different application release. Wastebin publishes versioned images using the quxfoo/wastebin:<VERSION> naming pattern. Verify that your intended version is published, replace latest with that exact tag, and test it in your environment.

Preserve the whole deployment state

A usable recovery plan needs more than state.db. Preserve the Compose file, the database, and any deployment-specific secrets such as the signing key and password salt. Store secrets separately from public source repositories. Document the host-side directory and ownership requirements so a replacement container can write to the restored database.

Expose the verified service with Localtonet

After Wastebin works locally, Localtonet can provide a public HTTPS address for its HTTP service. Our client establishes an outbound connection to a Localtonet relay server, so this workflow does not require inbound router port forwarding, a public IP address, VPN setup, or inbound firewall changes.

The local target remains Wastebin's host and port. If our client runs on the Docker host, use 127.0.0.1 and port 8088. If it runs elsewhere, use an address that the client device can actually reach and test that address from the client device before creating the tunnel.

HTTP and File Server tunnels can use a generated subdomain, a selected subdomain where supported, or a custom domain. Exact availability can vary. If you intend to use a custom domain, check the current DNS instructions before creating records because the authoritative setup details are not supplied here.

For the current dashboard sequence and available settings, consult our Localtonet HTTP tunnel documentation.

Test the complete request path

Use separate checks so you know which layer failed:

1. Open http://127.0.0.1:8088/ on the Docker host.
2. If our client is on another device, open the Wastebin host's reachable address from that client device.
3. Confirm that the Localtonet client is connected.
4. Confirm that the HTTP tunnel is started.
5. Open the assigned public HTTPS URL from a different network or device.
6. Create and retrieve a disposable, non-sensitive paste.

This sequence distinguishes an application failure from a Docker publication issue, a local network problem, a disconnected client, or a stopped tunnel.

Security boundaries and safer exposure patterns

Self-hosting controls where the application and SQLite database run, but it does not automatically make every access pattern private. Once a public tunnel is active, requests from the public internet can reach its configured local target. Wastebin's own documented limitations therefore remain relevant.

Temporary sharing

For occasional personal access, keep the Docker port on loopback, start the Localtonet HTTP tunnel only when needed, avoid storing sensitive material, and stop the tunnel when finished. This shortens the exposure window but does not transform an unauthenticated service into an authenticated one.

Long-running or public access

For persistent public availability, place a properly configured reverse proxy or another suitable access-control layer in front of Wastebin. Configure rate limiting there, and consider authentication, request-size restrictions, connection limits, logging, and any IP policy appropriate to your users. Point Localtonet at the protected proxy endpoint rather than bypassing it and targeting Wastebin directly.

This article does not prescribe a particular proxy configuration because no proxy product or verified policy has been supplied. Rate-limit values are workload-specific, and inventing universal thresholds would create a false sense of safety.

Minimize direct host exposure

When all components run on one host, bind the Docker publication to 127.0.0.1. If a separate Localtonet client must connect over the LAN, restrict the host firewall to that source where possible. Avoid exposing port 8088 through router forwarding in parallel with the tunnel, since that creates a second public path outside the intended workflow.

Do not put sensitive values in pastes

Even when using encrypted paste entries, apply normal secret-handling rules. Avoid copying authentication tokens, signing keys, private endpoints, production credentials, recovery codes, or customer data into a service merely for convenience. Encryption features reduce certain risks but do not remove endpoint security, password quality, availability, retention, backup, and operator-access concerns.

Troubleshooting Wastebin and the tunnel

The container exits or repeatedly restarts

Start with status and logs:

docker compose ps
docker compose logs wastebin

Look for a database write failure, migration error, invalid environment value, or occupied port. Validate the Compose file again with docker compose config. A restart policy can make a failure look busy without resolving its cause.

Wastebin cannot create state.db

Confirm that WASTEBIN_DATABASE_PATH is /data/state.db, the bind mount maps ./data to /data, and the host directory is writable by container user ID 10001. Inspect numeric ownership on Linux:

ls -ldn data
ls -ln data

Also confirm that data is a directory rather than a regular file and that the underlying filesystem supports the operations SQLite requires.

Database migration fails with extended SQLite error 6410

The Wastebin image is based on scratch. It does not contain a shell, and TMPDIR is not set by default. If migration fails with extended SQLite error code 6410, set TMPDIR to a directory SQLite can write to.

The existing /data mount is intended to be writable, so it can also be used as the temporary directory:

environment:
  - WASTEBIN_DATABASE_PATH=/data/state.db
  - TMPDIR=/data

Revalidate and recreate the service after editing the file:

docker compose config
docker compose up -d
docker compose logs wastebin

Docker reports that port 8088 is already allocated

Another process or container is using the host port. Stop the conflicting service or choose a different host-side port while leaving the container-side port at 8088. For example, a host port of 8090 would map to container port 8088. You would then test the host on port 8090 and configure Localtonet to target that host port.

The extracted evidence establishes Wastebin's internal default as port 8088. Changing only the left side of a Docker port mapping does not require changing Wastebin's internal listener.

The local page does not open

Verify that the container is running and that you are using the published host port. If the mapping is loopback-only, open it from the Docker host itself. A request from another device cannot use the Docker host's 127.0.0.1.

If Docker is running inside a virtual machine, remote development environment, or subsystem, its definition of the host may differ from your desktop's. Confirm where the port is published before changing Wastebin settings.

Pastes disappear after a restart

Confirm that the running container has WASTEBIN_DATABASE_PATH=/data/state.db and that the bind mount is active. If the variable was omitted, Wastebin's documented default is :memory:, which does not persist process state. Also verify that the paste did not expire and was not configured for deletion after reading.

The creator can no longer delete a paste after restart

Wastebin generates a random signing key at startup when WASTEBIN_SIGNING_KEY is not configured. Restarting then invalidates existing owner cookies. Configure and preserve a stable signing key of at least 64 bytes if this owner workflow needs to survive restarts.

Local access works but the public URL does not

Check the layers in order:

• Our client is running and connected.
• The selected device token corresponds to that client.
• The tunnel is started, not merely created.
• The selected relay server is currently available in the dashboard.
• The tunnel type is HTTP.
• The local target address is valid from the client device.
• The target port matches Docker's host-side published port.
• No local firewall blocks the client-to-Wastebin path.

If our client and Docker share a host, test http://127.0.0.1:8088/ there. If our client is remote, test the exact LAN address and port from that client device. Do not configure a remote client to target 127.0.0.1 unless Wastebin is also running on that remote client device.

The public page works, but QR codes show the wrong origin

Set WASTEBIN_BASE_URL to the current assigned public HTTPS address, validate the Compose file, and recreate the service. If the public hostname changes later, update this value again.

Frequently asked questions