Get started

Deploy your first app

Let's take the included starter app — a small React + Express app with login — from your machine to a live URL on your platform. No GitHub required.

Before you start

You should have Astrodock installed and running, and be able to log in to the dashboard. This guide uses a local install (admin.localhost); swap in your real domain if you're on a server.

Step 1 — Make the CLI runnable

The astrodock command lives in the repo you cloned. Install its dependencies once, then add a shortcut so you can call it from anywhere:

# from the astrodock repo folder
npm install

# add a handy alias (adjust the path to where you cloned it)
alias astrodock="node $(pwd)/packages/cli/bin/astrodock.js"

Check it works:

astrodock help

Tip

Add that alias line to your ~/.zshrc or ~/.bashrc to make it permanent. There's also a shorter alias, adock.

Step 2 — Get a copy of the starter app

Copy the example out of the repo so you can make it your own:

cp -r examples/starter-app ~/my-first-app
cd ~/my-first-app

Have a look at app.json — this is the file that tells Astrodock what your app is:

{
  "schemaVersion": "1",
  "slug": "starter",
  "name": "Starter App",
  "subdomain": "starter",
  "source": { "branch": "main" },
  "runtime": { "type": "node" },
  "auth": { "mode": "platform" },
  "database": { "mode": "none" },
  "storage": { "mode": "none" }
}

It will be served at starter.localhost and uses platform login (so users sign in with accounts you manage in Astrodock).

Step 3 — Create an API token

The CLI authenticates with a token. In the dashboard, open Tokens → New token, give it a name (e.g. "my laptop"), and copy the value — it's shown only once.

Step 4 — Point the CLI at your platform

export ASTRODOCK_URL="http://admin.localhost"
export ASTRODOCK_TOKEN="tk_paste-your-token-here"

Step 5 — Create the app

From your app folder, run apply. This reads app.json, creates the app on the platform, and sets up its resources and routing:

astrodock apply

You'll see it create the app and (because this app uses platform login) print an app secret once — the starter reads it automatically from the environment, so you don't need to copy it down for this tutorial.

Step 6 — Deploy it

Now ship the code straight from your laptop and watch it go live:

astrodock deploy:watch --local

The --local flag uploads your current folder (no GitHub needed). Astrodock builds it, starts it, and streams the log until it finishes:

Uploading 12 KB for "starter"…
Local deploy triggered for "starter" (deployment …)
[…] Installing server deps…
[…] Building frontend (npm run build)…
[…] Health probe: app is responding
[…] Deploy complete

✓ deploy success

Step 7 — Create a user who can log in

This app uses platform login, so you need a user account and that user must be granted access to this app. In the dashboard:

  1. Open Users → New user, set an email + password.
  2. Open that user and grant access to the starter app.

Two kinds of accounts

Your admin login (the dashboard) is separate from app users (people who log into your deployed apps). More in Manage users & access.

Step 8 — Open your app 🎉

Visit http://starter.localhost and log in with the user you just created. You're looking at your own app, on your own platform, with login handled for you.

Recap

You just did the whole loop: apply (create) → deploy:watch --local (ship) → grant access → log in. From here you'll usually connect a GitHub repo so pushes deploy automatically, but the manual loop above always works.

What's next