From laptop to server
Code that works on your machine still has to run somewhere else, for real users, without you watching. Why 'works on my machine' happens, configuration in the environment, locked dependencies, the main ways to host an app, CI that builds and tests every push, logs, health checks, and how to deploy without fear.
Everything so far ran on your own machine. You started it, watched it, and stopped it. Production is different: the code runs on a computer you may never log into, for people you’ll never meet, at three in the morning, with nobody watching. This part is about the gap between “it works on my laptop” and “it works for users”, and the habits that make crossing it boring, which is exactly what you want.
“Works on my machine”
The classic deployment bug: tested locally, deployed, broken. The code is the same. Something around it isn’t.
A small PHP app on a Mac or Windows laptop includes src/report.php, but the file is actually named Report.php. Those file systems usually ignore case, so it works. The server runs Linux, which doesn’t:
PHP Warning: require(…/src/report.php): Failed to open stream: No such file or directory in …/index.php on line 2
PHP Fatal error: Uncaught Error: Failed opening required '…/src/report.php'
The usual suspects when production behaves differently:
- Operating system: case-sensitive paths, line endings, path separators.
- Versions: PHP 8.1 locally, 8.3 on the server; Node 20 here, 22 there.
- Dependencies: a library updated itself between your install and the server’s.
- Configuration: a missing environment variable, a different database, debug mode on or off.
- Data: production has 50,000 rows, odd characters, and empty fields your test data didn’t (part 10).
The Twelve-Factor App, a widely cited set of guidelines for deployable apps, says it in one line: “Keep development, staging, and production as similar as possible.” The rest of this part is about how.
Configuration lives in the environment
Some things must differ between your laptop and production: the database address, API keys, whether debug mode is on. Twelve-Factor defines config as “everything that is likely to vary between deploys” and asks for “strict separation of config from code”. Its answer: “The twelve-factor app stores config in environment variables”.
def load_settings():
return {
"debug": os.environ.get("APP_DEBUG", "false") == "true",
"database_url": os.environ["DATABASE_URL"],
"payment_key": os.environ["PAYMENT_KEY"],
}
The same code, two environments:
debug: True | database: localhost/shop | payment key set: True
debug: False | database: db.internal/shop | payment key set: True
No if production: branches, no secrets in the repository (parts 16 and 22). Locally you keep them in a .env file that’s in .gitignore; on the server, the hosting platform or the system sets them. Missing required settings should stop the app at startup, as in part 13, not fail later on the first payment.
Lock your dependencies
package.json, composer.json, and requirements.txt usually say “version 4 or newer”. Without a lock file, your laptop and the server can install different versions on different days. The lock file (package-lock.json, composer.lock, poetry.lock or pinned requirements) records the exact versions that were tested.
Commit it, and install from it on the server. For npm that’s npm ci: “This command is similar to npm install, except it’s meant to be used in automated environments such as test platforms, continuous integration, and deployment”. It requires the lock file and “will never write to package.json or any of the package-locks: installs are essentially frozen.” PHP’s equivalent is composer install (not update) with composer.lock committed.
Build, then run
Many projects have a build step that turns source into something runnable: compiling Go, bundling JavaScript and CSS, generating a static site. This website is an example. npm run build turns Markdown and Astro components into plain files:
[build] 93 page(s) built in 5.36s
131 files, 5.3 MB, all static HTML, CSS, images, and the RSS feed. Nothing runs on the server except a web server handing out files, which makes it fast, cheap, and hard to break.
Keep the build separate from running: build once, test that exact output, and ship that exact output. Building again on the server, with possibly different versions, brings back the “works on my machine” problem.
Where code can run
There are a few broad options, from least to most work for you:
- Static hosting (Vercel, Netlify, Cloudflare Pages, GitHub Pages): for sites that are just files, like this one. Push to Git, the platform builds and serves it worldwide.
- Platform as a service (Railway, Render, Heroku-style platforms, Laravel Cloud, managed app runners): you give it code and environment variables; it runs processes, handles HTTPS, and restarts them when they crash.
- Containers (Docker, then a platform that runs them): “Docker is an open platform for developing, shipping, and running applications.” You describe the whole environment (OS packages, language version, your code) in a file, build an image, and “A container is a runnable instance of an image.” The same image runs on your laptop and in production, which closes most of the gaps above.
- A server you manage (a VPS with Ubuntu, for example): the most control and the most responsibility. A typical PHP setup is nginx in front, PHP-FPM running the code, a database, HTTPS certificates, a firewall, and updates you must apply yourself.
None of these is “the right one”. Many teams start simple and move only when they have a reason.
Development servers are not production servers
The quick servers you used locally, php -S from part 18, flask run, python -m http.server, are built for convenience. Flask’s documentation is direct: “Do not use the development server when deploying to production. It is intended for use only during local development.” PHP’s manual says the same about its built-in server.
Production uses servers built for many concurrent users (part 21) and for staying up: nginx or Apache with PHP-FPM, Gunicorn or uvicorn for Python, Node behind a process manager, or whatever your platform provides. nginx’s guide sums up how it works in one line: “nginx has one master process and several worker processes.”
CI: let a machine check every push
Continuous integration means every push runs the same checks automatically. “GitHub Actions is a continuous integration and continuous delivery (CI/CD) platform that allows you to automate your build, test, and deployment pipeline.” A workflow for a Node project like this site:
name: ci
on:
push:
branches: [main]
pull_request:
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
- run: npm ci
- run: npm test --if-present
- run: npm run build
It runs on a clean Linux machine every time, so “it built on my laptop” stops being enough: if the case-sensitive require above slipped in, CI would catch it before users did. The tests from part 14 and audits from part 22 belong here too. Continuous delivery is the next step: if CI passes on main, deploy automatically. That’s how this site works on Vercel: push, build, live.
Once it’s running: logs and health
When something breaks in production, you can’t attach a debugger. You have logs and metrics.
- Logs: Twelve-Factor says to “Treat logs as event streams”: “each running process writes its event stream, unbuffered, to stdout.” The platform collects them. Write structured lines (part 15) so they’re searchable:
{"path": "/health", "status": "200"}
- Health checks: a small endpoint that says whether the app can do its job, used by load balancers and monitoring:
$ curl http://127.0.0.1:8097/health
{"status": "ok", "version": "1.4.2", "uptime_s": 0}
Including the version makes “which code is actually running?” a one-line answer. Return 503 when a dependency like the database is unreachable, so traffic is sent elsewhere.
- Alerts: errors and slow responses should reach you before users have to tell you. Error trackers and uptime monitors exist for this.
Deploying without fear
A deploy is a change to a running system, so the habits from Git (part 16) and refactoring (part 17) apply:
- Small, frequent deploys are safer than big, rare ones. If something breaks, you know which change did it.
- Know how to roll back before you need to: redeploy the previous version, or
git revertand push. - Database migrations need care. Code can be rolled back in seconds; dropped columns can’t. Make schema changes backward-compatible: add the new column, deploy code that uses it, and remove the old one in a later deploy.
- Back up data and test the restore. A backup you’ve never restored is a hope, not a backup.
- Avoid Friday-evening deploys unless you’re happy to spend the weekend on them.
Why this matters day to day
- Software only matters once it’s running for users. Deploying is part of the job, not someone else’s problem.
- Most production incidents are environment problems: config, versions, data, not logic.
- Automation removes whole classes of mistakes. A CI pipeline never forgets to run the tests.
- AI tools can write deployment scripts and configs quickly, but can’t see your server. Check versions, secrets, and what happens on failure before you run them.
Try it yourself
- List every environment variable your app needs. Does it fail clearly at startup if one is missing?
- Make sure your lock file is committed, and use
npm ciorcomposer install(notupdate) when deploying. - Add a CI workflow that installs dependencies, runs tests, and builds on every push.
- Add a
/healthendpoint that reports the version and checks the database. - Write down, step by step, how you would roll back your last deploy. Then try it on a staging copy.
Summary
- “Works on my machine” comes from differences in OS, versions, dependencies, config, and data. Keep environments as similar as possible.
- Config in environment variables, secrets out of the repository, fail fast when something is missing.
- Lock dependencies and install from the lock file (
npm ci,composer install). - Build once, test that output, ship that output.
- Hosting ranges from static to platform to containers to your own server; pick the simplest that fits.
- Development servers are not for production.
- CI builds and tests every push on a clean machine; CD deploys what passes.
- Logs to stdout, a health check, and alerts are how you see production.
- Small deploys, a known rollback, careful migrations, tested backups.
References
- The Twelve-Factor App: Config, Dev/prod parity, and Logs.
- npm ci, npm documentation.
- Understanding GitHub Actions, GitHub Docs.
- What is Docker?, Docker documentation.
- Deploying to Production, Flask documentation; Beginner’s Guide, nginx documentation.