Private beta guide

Thank you for testing Portdeck. This page is the short path from nothing to a running app, what to expect, and how to tell us when something breaks. The beta is private and the software is early. Expect rough edges.

When a page here says "coming", that feature does not exist yet. Do not look for it.

What you need

• A Linux server or VM with Docker Engine and the Compose v2 plugin.
• 2 GiB of memory (4 GiB is better) and 4 GiB of free disk.
• A second machine to connect as a server, if you want to test that part. It needs Docker.
• A beta license key from us. See Your beta key.

You need no account with anyone else. No Cloudflare, no email provider. You do not need GitHub access either: this guide and the checklist are on the website, and you report problems by email.

1. Install in one command

Run this on the server:

curl -fsSL https://get.getportdeck.com/install.sh | sh

The installer asks what it needs and explains each question as it goes. It generates all secrets and prints where they are. It does not print the secrets.

Pick how people reach Portdeck (the access mode):

• caddy-domain: a server with a public IP and a domain. Built-in Caddy gets a Let's Encrypt certificate. You create one DNS record.
• caddy-private: a LAN, VPN or Tailscale. Built-in Caddy with its own certificate authority.
• proxy: behind your own reverse proxy. You route three hostnames: the web app, the ops console and the agent gateway (a WebSocket).
• tunnel: no public IP. Needs a Cloudflare Tunnel token.
• direct: plain HTTP, for trying Portdeck on a laptop, a VM or a LAN. Keep it on a network you trust.

For a first try on a private network, caddy-private or direct is the least work. For a real domain, use caddy-domain. You can pass the choice to the installer, for example --access-mode caddy-domain --domain portdeck.example.com.

The installer prints the path of the install directory when it finishes (the examples below use ~/portdeck). Your .env file and the backups/ folder live in that directory.

When it finishes, do these three things:

1. Open the ops console address it printed.
2. Sign in as admin with the password in first-admin-password.txt.
3. Set up two-factor when asked, change the password at once, then delete first-admin-password.txt. The ops console has no change-password page, so run this in the install directory (the new password lands in your shell history; start the line with a space if your shell ignores such lines): docker compose exec web python -m app.cli reset-password --internal admin '<new password>'

Then copy age-private-key.txt somewhere offline and delete it from the server. Without that key, your backups cannot be restored.

2. The first-run wizard

After you sign in to the ops console, a setup wizard opens. It has six steps: your account, how people reach Portdeck, the first workspace owner, a license (optional), your first server, and a summary. Every step can be skipped and done later.

The wizard shows only on a fresh install. Finishing or skipping it closes it.

3. Connect a server

A server joins Portdeck through a small program, the agent. The server needs no open port and no SSH key for Portdeck.

1. In the wizard (step 5) or on the Hosts page, add a server and give it a name. Portdeck shows a one-line install command with a one-time token. It is valid for one hour.
2. Run that command on the server with sudo.
3. In a few seconds the server shows as connected.

Use the command the wizard shows, with the addresses it prints.

The agent address must be reachable from the other server. With caddy-domain or proxy mode, make sure the agent gateway address works from outside.

4. Deploy an app

1. Open Launch and choose Launch an instance.
2. Give it a name, pick an image from the approved list, a size, and a port.
3. Click Launch instance. The status should change to Running.

With the built-in Caddy (caddy-domain or caddy-private), you can give an app a public address on the same machine as Portdeck, from the instance's Access tab. Apps on other servers do not get a URL this way yet.

To build an app from your own GitHub repository, set up a pipeline. It asks for a GitHub token, which you add in Settings.

5. Update an app

There is no Update button yet. Today you update an app in one of these ways:

• Push to a repository with a pipeline. The app is rebuilt and redeployed.
• On a pipeline's Runs page, use Deploy version to deploy a tag that already exists.
• To change an app's environment variables, use Save and redeploy on its instance page. This redeploys the same image. It is not an Update button.
• On an instance's Deploy tab, use Roll back to this to go to an earlier version.

A redeploy that does not become healthy is rolled back by itself.

Portdeck also checks which Docker version each app runs and whether its registry has a newer tag. It does this every 6 hours. The result is not shown in the interface yet: there is no "update available" badge. For now, check the version of your own apps when you redeploy.

6. Upgrade Portdeck

Nothing updates by itself. You choose when. From the install directory:

cd ~/portdeck
bin/upgrade.sh status
bin/upgrade.sh --version <NEW-VERSION> --dry-run
bin/upgrade.sh --version <NEW-VERSION>

The upgrade takes an encrypted backup first. If the new version is not healthy and the database schema did not change, it rolls back by itself. If the schema did change, it stops and asks you to choose. If that happens, write to us before you choose.

Beta versions are numbered 0.x.y. Only the newest release is supported.

Your beta key

We give you a beta license key by hand. Where it comes from:

• We send it to you directly when you join the beta. Do not post it anywhere.
• A beta key gives the Enterprise plan: the Pro and Enterprise features that exist today. It is valid for 90 days from the day we issue it.

To use it: in the ops console open Security & admin, then Licenses, paste the key and click Check key. Keys are checked offline. Nothing is sent to us. If the Licenses page says the key cannot be verified, tell us.

The beta agreement appears after Check key, in the preview. Read it. You must tick "I have read the beta agreement above and accept it". Activate this key works only once the box is ticked.

In the first-run wizard (step 4) the same thing is a collapsed section, "Private-beta key? Read and accept the beta agreement". Open it, read it, tick the box, paste the key and click Check and activate.

Until you accept, the key is not in use. The install stays on the trial or Community, and the Licenses page says so. Nothing is deleted or stopped. If the key is set as PORTDECK_LICENSE_KEY in .env, the Licenses page shows a "Beta agreement needed" box with the same tick box.

Accepted beta keys are listed under Beta keys on the Licenses page. Only a fingerprint of each key is kept, never the key.

Every install also starts with a 14-day trial. Without a valid key after the trial, Portdeck falls back to the Community limits: 3 servers and 1 workspace. Nothing you already have is deleted or stopped. When a key expires, the same happens.

What works today

• One-command install on a single server, with built-in HTTPS (Caddy), your own reverse proxy, a Cloudflare Tunnel by token, or plain HTTP.
• The ops console with its own sign-in and mandatory two-factor.
• The first-run wizard.
• Workspaces: roles, the switcher, invites with a link to copy, hosts per workspace.
• Connecting servers with the agent, and running Docker apps on them.
• Pipelines from a GitHub repository, deploy history and rollback.
• Logs, start, stop, restart, delete.
• Public URLs for apps on the same machine as Portdeck, through the built-in Caddy.
• Encrypted daily backups, kept on the server.
• Plans, the 14-day trial and license keys.
• Upgrade and rollback with bin/upgrade.sh.
• Version detection for Docker apps, through the API.

Coming, and not in this beta

These do not exist yet. Do not report them as bugs.

• An Update button and an "update available" badge in the interface.
• Environments, pull request previews, deploy policies.
• Single sign-on (SSO) and SCIM.
• The client portal.
• Scanning images when they are deployed (a Trivy scan can be switched on in a pipeline's generated GitHub workflow, but Portdeck does not scan at deploy time).
• Public URLs for apps on other servers, and wildcard certificates.
• A DNS provider integration.
• Backups copied off the server. You can add that yourself.
• Automatic updates, high availability, an uninstaller.
• Anonymous usage statistics.

Known limitations

• Single node. Portdeck runs on one server. There is no high availability.
• Backups are on the same disk as the database until you copy them elsewhere. Copy backups/ and your .env off the server.
• There is no change-password page in the ops console. Use the command in section 1.
• Agents do not verify the gateway yet. See the warning in section 3.
• Images are pulled by tag, not by digest, and the installer is checked by checksum only, not by signature. The installer downloads over HTTPS and checks the bundle against a .sha256 file from the same place. That catches a damaged download but is not authentication.
• No test of a restore on a fresh machine yet. Test your own restore early.
• Where this guide and the interface disagree, trust the interface and tell us.
• Only the latest beta release is supported.

Report a problem

Email beta@getportdeck.com. You do not need a GitHub account.

Please include:

• the Portdeck version (bin/upgrade.sh status),
• the install mode,
• what you did, what you expected, what happened,
• logs from docker compose logs <service> in the install directory.

Security problems: do not report them in public. Write to security@getportdeck.com instead. Use that address only for security problems.

A checklist of things to try is in the tester checklist.