A free chapter from Start Here: It Works on My Machine
Chapter 13. Put it on the internet
Rule 13: When a deploy fails, read the log before anyone fixes anything.
So far, everything you've built lives on your computer. It works there. Of course it works there. "It works on my machine" is the oldest line in software, and it has never once impressed a customer.
This chapter moves your site onto a computer you don't own, one that's switched on all night and has an address anyone can type. That computer is called a host. Sending your site to it is called a deploy. By the end of the chapter you'll have a real link you can text to a friend.
First, the part the weekend videos cut.
The first time: it found my project and just went for it
In November 2025 I signed up with a host, pointed it at my PocketSense project, and watched. It found the project and started building before I'd finished reading the screen. I remember being impressed for about ninety seconds.
Then it stopped. The host couldn't work out what kind of project it was looking at. My app had its back end in one folder and its front end in another, in two different programming languages, and nothing at the top that said so. My AI partner asked where my list of required packages was. I had to admit I didn't think we'd ever made one. On my machine everything was already installed, so nothing had ever asked.
We fixed that. The next build failed on a different line. The build ran a strict install command that only works from an exact, saved list of versions, called a lockfile. I had one. It was on my computer. I'd never committed it.
Notice the pattern. Both failures were the same failure. My computer knew things my project didn't say. The host only gets what's in the repository.
It wasn't over. A few weeks later a build died and my AI partner told me, with total confidence, to fix line 31 of a particular file. I said that file wasn't in my project. It told me again. I said it again, in capital letters. We were both right. The host had written that file itself, during the build, and the log was quoting the host's own copy. My partner had a theory before it had the facts, and I spent a good while arguing with a guess.
Around then I started sending the whole log with one line on top: here's the log, think it through, don't fix anything yet.
The second time
A year later I built wetherell.org, the site this book is sold on, from an empty folder. The first commit went in at 2:28 in the afternoon. At 6:06 that evening there's a commit that changes one line of the build so it installs from the lockfile, exactly, every time. The lockfile was already committed. Nobody had to learn that lesson. It was in the plan.
Before 8:00 that night I'd made the commits that put the site at its own address and opened it to search engines. The first deploy went green on the first try.
Same builder. Same kind of host. The difference was a year of rules, and this chapter is the short version of them.
Do it
Everything here happens in a browser and in your agent's chat, so Mac and Windows are the same. I use Railway as my host and I'll use its button names. I'm not affiliated with them. If you pick another host, you want one that deploys straight from GitHub, shows you full build logs, and lets you hold a deploy until your checks pass.
1. Hang the closed sign. Make it true: search engines are asked not to list the site yet. A half-built site in search results is hard to take back. Send your agent:
SESSION: your site project
Set the site so every page tells search engines not to index it,
with one switch I can flip at launch. Show me the line that does it
and how you checked a built page for it. Change nothing else.2. Ask what the host will see. Make it true: you know what happens before it happens. This is the kit's deploy-recon.md.
SESSION: your site project
RECON ONLY. Change nothing.
A host is about to build this project from GitHub. Tell me:
1. What file tells the host how to build and start the site? Quote it.
2. What port does the site listen on, and where is that set?
3. Is the lockfile committed? Show me the git command that proves it.
4. Is anything needed to build that exists on my computer but not in the repository?
5. Is there any password, key or personal detail in the repository?
STOP. Wait for me.Read the answer. Check one claim yourself. If number 4 or 5 turns anything up, fix that first, as its own small job.
3. Open the host account. Sign in with GitHub and turn on two-step sign-in, like every account in Chapter 6. When I checked in November 2026, a new Railway account got a one-time $5 of free credit, and the Hobby plan was $5 a month with $5 of usage included. A small site like this fits inside that. Prices change, so look before you count on mine. Write it on your accounts-and-costs sheet.
4. Connect one repository. Click New Project, then GitHub repo. GitHub will ask what the host may see. Choose only this repository, not all of them. Pick your site, then Deploy Now.
5. Watch it build. Touch nothing. Open the deployment and read the log as it scrolls. You'll see it fetch your code, install, build, and start. This is the one time I'll tell you to sit and watch a progress bar. You're learning what normal looks like, so you'll know what odd looks like.
6. Get a test address. In the service's settings, click Generate Domain. It didn't ask me for a port, it worked that out for itself. If yours does ask, give it the one from step 2. You'll get an address ending in up.railway.app.
7. Look at it like a stranger. Open the address on your phone, not the computer you built it on.
8. Make checks hold the door. In the service settings, turn on Wait for CI. From now on a push only goes live after the automatic checks from Chapter 12 pass. The switch only appears if those checks exist and run on every push, which is one more reason Chapter 12 came first.
9. Run the loop once. Ask your agent for one tiny visible change, a word in the footer. Review it, push it yourself, and watch the host pick it up without you asking. That loop is the rest of your life with this site.
You'll know it worked when
- The address opens on your phone with a padlock in the address bar.
- A page that doesn't exist shows your not-found page, not the host's.
- Your one-word change showed up on its own a few minutes after you pushed.
- Your agent can show you the do-not-index line in the live page.
When it doesn't
Treat your first deploy like the Kobayashi Maru. You're probably going to lose it. The test is what you do next.
What you do next is nothing, for one minute. Don't click redeploy. Don't let your agent start typing. Copy the whole log, top to bottom. Railway's own guide says the real error is rarely at the bottom, and that matches my experience. Then send this, the kit's read-the-log.md:
SESSION: your site project
The deploy failed. Full log below. Do NOT fix anything yet.
1. Quote the first line where something went wrong, not the last.
2. Does every file that line names exist in our repository? Check, don't assume.
3. Give me one theory, with the evidence for it from the log and from our files.
4. Tell me what you'd change and what you're not sure of.
STOP. Wait for me.
<paste the whole log>The usual suspects, the first two from my own first week:
| What the log says, roughly | What it usually means |
|---|---|
| It can't decide how to build your project | Nothing in the repository says what kind of project this is. Your computer knew. The host doesn't. |
| The install step refuses to run | The lockfile isn't committed. |
| It built fine, but the address shows an error page | The host is knocking on the wrong port. Give it the one from step 2. |
| It can't find a file you can see on your screen | The file was never committed, or its name differs by a capital letter. |
Rule 13, in plain words
What it means. A failed deploy comes with a written account of what happened. Read that first. Nobody proposes a fix, not you and not the agent, until someone has quoted the line that failed.
Why it exists. A deploy takes minutes, so a wrong guess costs minutes, and three wrong guesses cost your evening. An agent will always have a theory ready. A theory that came before the reading is just a guess with good grammar.
What it looks like. The whole log, one prompt that says don't fix, one quoted line, one theory with evidence. Then you say go.
The template
Two files in The Start Here Kit: deploy-recon.md (step 2) and read-the-log.md (the failure prompt). The nine steps are also in first-prompts.md as a one-page tick-sheet.
Make it yours
- If watching a log makes your eyes glaze, ask the agent to summarize a good build once, in five lines. Keep it. Next time, ask what's different.
- If money is tight and your host offers a spending limit, set it on day one. I'd rather have a site that pauses than a bill that surprises me.
- If you chose a different host, do step 2 anyway. The questions don't change.
Try it
What I noticed: