How to Self-Host PicoShare in 2026: Uploads, Shared Secrets and Storage

Self-hosting PicoShare becomes interesting at the first redeploy, not the first docker run. If uploads hit proxy limits or files disappear with an ephemeral /data path, Docker can still report a perfectly healthy process. The deployment below is organized around observable behavior: upload a file, download it from a fresh browser, test expiration or deletion and retry with a file near the chosen size limit.

The intended job of PicoShare is explicit: minimal file sharing that turns uploads into links. That description tells us what must stay public, what should remain private and what a backup has to reconstruct.

Make PicoShare recovery measurable

Make a recovery manifest for PicoShare: uploaded files and PicoShare metadata in /data. Mount /data before bootstrap, write harmless sample data and replace the container to prove that path is actually persistent. Check ownership and free space now, because a mounted but unwritable path behaves like no persistence at all.

Back up to a failure domain separate from the running server. Recreate PicoShare from its pinned image and verify that uploaded bytes and metadata return and a sample of existing links downloads files with matching hashes. The persistent-volume guide helps translate that exercise into snapshot and retention policy.

The production shape of PicoShare

The PicoShare HTTP process listens on 4001; keep that port on the application network and publish only the platform route. The local runtime requirement is a durable data volume and enough disk for retained files. Document the expected capacity, ownership and failure mode rather than leaving it as an image default.

Write the boundary down as a short contract: who owns the requirement, which credential is used, what timeout is acceptable and how failure appears. Then run this transaction: upload a file, download it from a fresh browser, test expiration or deletion and retry with a file near the chosen size limit. Observe disk capacity, upload bandwidth, proxy body limits and concurrent downloads during the run, because that workload gives a more useful starting size than an idle container.

The PicoShare release gate

Convert the PicoShare smoke test into a repeatable release command or short runbook. Its output must demonstrate this outcome: upload a file, download it from a fresh browser, test expiration or deletion and retry with a file near the chosen size limit. Record the application version, container digest, route hostname and test-data identifier with the result.

Run the same check after a routine container swap and after restoring uploaded files and PicoShare metadata in /data elsewhere. The restore has succeeded when uploaded bytes and metadata return and a sample of existing links downloads files with matching hashes. Compare timing and consumption related to disk capacity, upload bandwidth, proxy body limits and concurrent downloads; a large change is worth investigation even when the final action still passes.

Then exercise a safe failure: submit harmless input near the resource or format limit associated with this boundary: uploads hit proxy limits or files disappear with an ephemeral /data path. Confirm that PicoShare surfaces the fault and returns to normal without destructive manual edits. Preserve only the necessary, redacted log excerpt. This four-part gate covers startup, persistence, recovery and failure handling.

Container settings worth reviewing

Start PicoShare in a way that leaves the route private until bootstrap is complete.

docker run -d \
  --name picoshare \
  --restart unless-stopped \
  -p 127.0.0.1:4001:4001 \
  -v picoshare-data:/data \
  -e PS_SHARED_SECRET=replace-with-a-long-random-value \
  mtlynch/picoshare:latest

If the process loops, compare the image's expected user with the owner of each mounted path. If it stays up, test port 4001 locally and then move directly to the workflow: upload a file, download it from a fresh browser, test expiration or deletion and retry with a file near the chosen size limit. Version-pin the image only after that end-to-end check passes, and record the exact configuration beside the service.

Reduce the authority held by PicoShare

Bootstrap credentials are temporary; the trust model is permanent. With PicoShare, watch for using a guessable shared secret or offering unlimited anonymous storage, and use a long shared secret, rate-limit uploads and avoid turning the service into anonymous unlimited storage.

Replace the sample PS_SHARED_SECRET immediately, store it outside the image and rotate it like an administrator credential if it is exposed. Run the image without unnecessary Linux capabilities and expose only the public application route. Keep administrator activity visible without recording secret values.

Route PicoShare without lying about HTTPS

Avoid temporary and permanent public origins for PicoShare. Instead, publish one HTTPS origin and size the proxy for expected uploads, point the chosen DNS name at the platform route and proxy only to port 4001.

Exercise this action from outside the host: upload a file, download it from a fresh browser, test expiration or deletion and retry with a file near the chosen size limit. If ingress fails, the 502 troubleshooting guide covers port and listener mistakes. If PicoShare receives the request but uploads hit proxy limits or files disappear with an ephemeral /data path, the evidence now points beyond the proxy.

Capacity and upgrade checks

An idle health check says little about PicoShare. Watch disk capacity, upload bandwidth, proxy body limits and concurrent downloads, then alert on the symptom users experience: failure of the action “upload a file, download it from a fresh browser, test expiration or deletion and retry with a file near the chosen size limit”. Keep liveness local and cheap; let readiness report migrations or initialization without causing a restart storm.

The risky upgrade area is that PicoShare metadata and file layout should be checked before an upgrade because the link is useful only while both agree. Read release notes, snapshot state, deploy the target version against a restored copy and repeat the acceptance action. If uploads hit proxy limits or files disappear with an ephemeral /data path, correlate the client request with the first relevant application log rather than deleting state or adding redirects blindly.

Deploy PicoShare on Dockup without losing its boundaries

Dockup removes manual reverse-proxy and lifecycle work around PicoShare. The service receives a stable HTTPS route to 4001, injected configuration and persistent storage during replacements. An attached customer server follows the same model as Dockup-hosted compute.

After launch, satisfy the application contract: publish one HTTPS origin and size the proxy for expected uploads, confirm the local requirement — a durable data volume and enough disk for retained files and run this proof: upload a file, download it from a fresh browser, test expiration or deletion and retry with a file near the chosen size limit. This keeps the one-click experience useful without flattening the details that make PicoShare recoverable and secure.

Frequently asked questions

What does PicoShare need for a production deployment?

Route the PicoShare container on port 4001 through one HTTPS origin. The local runtime requirement is a durable data volume and enough disk for retained files. Do not call PicoShare ready until you can upload a file, download it from a fresh browser, test expiration or deletion and retry with a file near the chosen size limit.

Which PicoShare data belongs in a backup?

Persist /data and include uploaded files and PicoShare metadata in /data in the same recovery manifest. A clean PicoShare restore passes only when uploaded bytes and metadata return and a sample of existing links downloads files with matching hashes.

Does PicoShare require HTTPS behind a reverse proxy?

Use HTTPS for the public PicoShare origin and keep port 4001 on the internal route. Apply the PicoShare setting correctly: publish one HTTPS origin and size the proxy for expected uploads. For PicoShare, HTTPS protects credentials or user content in transit and keeps origin-sensitive client behavior consistent.

How should a PicoShare upgrade be tested?

Restore current PicoShare state into an isolated deployment, apply the candidate version and repeat its acceptance transaction. Pay particular attention because PicoShare metadata and file layout should be checked before an upgrade because the link is useful only while both agree. Keep the previous PicoShare image until its data-migration and rollback boundary are understood.