Add a One-Click Deploy Link to Your Project's README

·5 min read·Updated
open-sourcedockerdeploymentself-hostedhow-to

If you maintain a self-hostable project, you can give people a one-click deploy link that opens a create form with your image, ports, volumes, and environment variables already filled in — all encoded in a plain URL. There's no manifest file to add to your repository, no template to submit for review, and nothing to keep in sync when your image changes. You build the URL once, put it behind a badge in your README, and anyone who clicks it lands one button away from a running copy of your software.

Why a URL and not a manifest

The established pattern for this is a file in your repository: app.json for a Heroku button, render.yaml for a Render blueprint, a submitted template for other platforms. They're more powerful — multi-service stacks, generated secrets — and they cost more to maintain. You're adding a vendor-specific file to your repo, keeping it current, and in some cases waiting on approval.

A deploy link is the low-ceiling, low-effort end of that trade:

  • Nothing in your repository. The configuration lives in the link, so it works for projects that don't want a platform's file in their tree.
  • Nothing to approve. You construct it yourself and it works immediately.
  • Easy to vary. Ship one link for the minimal setup and another with your recommended volumes and env vars pre-filled, without touching your codebase.

The trade-off is real: one image per link, and no secret generation. For a single-container tool, that's the whole configuration anyway.

The URL

The form lives at /panel/add/from/docker/registry, and it reads its initial state from the query string:

https://justrunmy.app/panel/add/from/docker/registry
  ?img=louislam%2Fuptime-kuma%3A2
  &vol=%2Fapp%2Fdata
  &port=3001
  &protocol=HTTPS

Open that and the create form comes up already describing Uptime Kuma.

The Existing Docker Image create form in the JustRunMy.App panel with the image field pre-filled from a shared deploy link

The parameters:

Parameter Meaning Example
img Image reference, repository[:tag] louislam/uptime-kuma:2
cmd Run command, if the image needs one redis-server /etc/redis.conf
reg Custom registry URL, for images outside Docker Hub ghcr.io
env Comma-separated KEY=VALUE pairs TZ=UTC,PUID=1000
vol Comma-separated container paths /app/data,/config
port Container port — repeat for multiple 3001
protocol HTTPS, TCP, or UDP — pairs with port by position HTTPS

URL-encode every value. Slashes in volume paths, the colon in an image tag, and the = inside env pairs all need escaping, or the query string won't survive the trip. /app/data becomes %2Fapp%2Fdata; uptime-kuma:2 becomes uptime-kuma%3A2.

port and protocol pair by index. Two ports means two of each, in the same order — the first protocol applies to the first port.

You don't have to assemble this by hand. Fill the form in the panel, expand Advanced, add your ports and volumes, then press Copy share link and it builds the URL for you. Constructing one manually is only useful when you're generating links programmatically or writing them into docs.

Putting it in your README

A shields.io badge and a link is all it takes:

[![Deploy](https://img.shields.io/badge/Deploy-JustRunMy.App-2ea44f)](https://justrunmy.app/panel/add/from/docker/registry?img=youruser%2Fyourapp%3Alatest&vol=%2Fdata&port=8080&protocol=HTTPS)

Point img at a tag you actually maintain. :latest is friendliest for a deploy button, since the link keeps working as you publish new versions — pin a version instead if your releases carry breaking changes and you'd rather people opt in.

Choose the defaults carefully

The link is the first experience someone has of your project, so the values in it are effectively your recommended configuration.

  • Pre-fill the volume. This is the highest-value parameter by far. Most self-hosted tools keep state in one directory, and someone deploying from a link won't know which one. Getting it right up front is the difference between "works" and "lost everything on the first update" — data outside a volume doesn't survive a redeploy.
  • Pre-fill the port with the right protocol. HTTPS for anything with a web UI — that gets a real certificate automatically. TCP or UDP for everything else.
  • Pre-fill only non-secret env vars. Timezone, feature flags, a base path: fine. Never put an API key, password, or token in a link you publish — it's a URL, it ends up in browser history, referrer headers, and anyone's screenshot. Leave those out and mention them in your README instead.
  • Say what it costs to run. A line about memory saves people from deploying something that won't fit. Small, mostly-idle tools are the sweet spot; anything that wants hundreds of megabytes before it does any work will be a poor experience on a small quota.

What it can't do

Worth being straight about the limits, since they decide whether this fits your project:

  • One container per link. An app plus a separate database is two links, or a link plus instructions.
  • No generated secrets. Nothing invents an admin password for the user the way a full template system can.
  • No health checks or post-deploy hooks. The link fills in a form; it doesn't script a setup sequence.

For a single-image tool with a volume and a port — which describes most self-hosted software — none of that bites.

FAQ

Fill in the create form under Existing Image, expand Advanced, add your ports and volumes, then press Copy share link. You can also build the URL by hand from the parameters above.

Do I need to add a file to my repository?

No. Everything is in the query string, so nothing about the platform lives in your project.

Can I pre-fill environment variables?

Yes, with env=KEY=VALUE,KEY2=VALUE2, URL-encoded. Only do this for non-secret values — a published link is public.

How do I specify more than one port?

Repeat both parameters: &port=80&protocol=HTTPS&port=5432&protocol=TCP. They pair up in order.

Does the person clicking it need an account?

Yes — the link opens the create form in the panel, so they sign in first and then click Create.

No. A link describes a single container. For a two-service setup, provide two links or point at the Postgres template for the database half.

Wrapping up

Most self-hosted software is one container, one data directory, and one port — and the gap between "here's my Docker image" and someone actually running it is mostly the part where they guess those three things correctly. A deploy link closes that gap with a URL you can paste into a README, and the useful work isn't the link itself but the defaults you choose to encode in it.