# Your first deployment
URL: https://openship.io/docs/getting-started/first-deployment.md

A gentle, screen-by-screen walkthrough of putting one real GitHub app online with Openship — and what "live" actually looks like.

import { Step, Steps } from 'fumadocs-ui/components/steps';

You're about to take some code that lives on GitHub and turn it into a real website that anyone can open. Think
of it like handing a letter to the post office: you give Openship your code, it does the sorting, stamping, and
delivering, and out the other end comes a real web address you can click.

This page is the slow, friendly tour — we stop at every screen and explain what it means. If you'd rather do the
whole thing from the terminal in a couple of commands, the [Quickstart](/docs/getting-started/quickstart) has you
covered.

<Callout title="Before you start">
- Openship is up and running (you can see the dashboard). If not, start with [Installation](/docs/getting-started/installation).
- You have a **GitHub repository** with an app in it — a website, an API, anything.
- You do **not** need Docker, a server config, or any special files. Openship figures those out by reading your repo.
</Callout>

## The walkthrough

<Steps>

<Step>

### Open a new project

In the dashboard, go to the **Library** page (the **New project** button lands you here too). It opens on the
**GitHub** tab, which shows a list of your repositories.

If this is your very first time, Openship won't have permission to see your repos yet — you'll see a **Connect
GitHub** button instead of a list. Click it, say yes in the GitHub window that pops up, and the list appears.
You only do this once.

<Callout title="Screenshot">Library page, **GitHub** tab — either the "Connect GitHub" prompt (first time) or the list of repositories. *(screenshot pending)*</Callout>

</Step>

<Step>

### Pick the repository you want

Find your app in the list and click it. Openship reads the repo, works out what kind of app it is, and takes
you to the setup screen. There's nothing to fill in by hand yet — just choose the repo.

</Step>

<Step>

### Choose where it should run (you might not see this)

Depending on how you're running Openship, it may first ask **"Where do you want to deploy?"** The choices are
things like one of your **connected servers** or **Openship Cloud** (the managed option, where Openship runs the
app for you).

If Openship already knows where to send your app — there's only one place available, or you chose one the last
time — it skips this screen and takes you straight to setup. So don't worry if you never see it. When you do,
pick one and press **Continue**.

<Callout title="Tip" type="info">
Not sure? The default is fine. This choice isn't permanent — you can move or redeploy the app later.
</Callout>

</Step>

<Step>

### Read the setup screen

This is the one screen worth a slow look. Openship has already filled it in for you by reading your code:

- **The framework and commands** — which kind of app it detected, plus the install and build commands it will run.
- **Environment variables** — an area to add any secrets or settings your app needs (like a database address).
  Empty is fine if your app doesn't need any.
- **Project name** — a short, unique name for this deployment.

On the right is a summary panel with your repository, its branch, the web address the app will get, and a
**Deploy** button.

For most apps you change nothing here. If you see a field you don't recognize, leave it — the detected defaults
are correct for the large majority of apps.

<Callout title="Screenshot">The Deploy setup screen: detected framework/build settings on the left, and the summary panel with the branch, web address, and the **Deploy** button on the right. *(screenshot pending)*</Callout>

When it looks right, press **Deploy**.

</Step>

<Step>

### Watch it go live

You land on the build screen. Two things are happening here:

- A **row of steps** across the top lights up one by one as each part finishes.
- A **live terminal** streams the build logs as they happen — like watching the oven through the glass door.

You don't have to do anything. When it's done, the title at the top changes to **Deployment Successful** and two
buttons appear: **Visit Site** and **View dashboard**.

<Callout title="Screenshot">The build screen after it finishes — "Deployment Successful", the completed step tracker, and the **Visit Site** button. *(screenshot pending)*</Callout>

</Step>

</Steps>

## What "live" looks like

When the deployment is done, the build screen shows a **Ready** status in the deployment details, along
with the branch it built, the framework it used, and the **web address** your app now lives at.

Press **Visit Site** and Openship opens that address in a new tab — that's your app, on the internet, for real. 🎉

<Callout title="Where does the web address come from?" type="info">
Openship gives every project a web address automatically — you'll see the exact one on the setup screen and again
in the build details. **Visit Site** just opens it. Prefer your own name, like `yourapp.com`? You can attach a
custom domain afterwards.
</Callout>

**View dashboard** takes you to the project's page, your home base for this app: its deploys, logs, environment
variables, and settings all live there.

## If something goes wrong

<Callout title="No repositories show up / “Connect GitHub” keeps reappearing" type="warn">
Your GitHub connection didn't finish, or Openship wasn't granted access to that repo. Connect again, and when
GitHub asks **which repositories** to allow, make sure yours is included.
</Callout>

<Callout title="The build failed" type="error">
Read the last few lines in the build terminal — that's the real reason, in plain text. First-time failures are
almost always one of three things: a missing build command, a missing environment variable, or the app listening
on the wrong port. Fix it in your repo (or in the setup screen), then redeploy.
</Callout>

## What next?

<Cards>
  <Card title="Deploy from GitHub" href="/docs/guides/deploy-from-github" description="The same flow as a quick reference — plus how to redeploy automatically on every push." />
  <Card title="Quickstart" href="/docs/getting-started/quickstart" description="Do it all from the terminal in a couple of commands." />
  <Card title="Multi-service apps" href="/docs/guides/compose-multi-service" description="Deploy an app that's really several services at once (a docker-compose stack)." />
</Cards>