Deploy an App Built with Cursor: A Step-by-Step Guide

Deploy a Cursor-built app by containerizing it, pushing to GitHub, and picking a hosting platform. Cursor can generate a Dockerfile with a prompt. The simplest path: Ship (flat rate EUR 10-20/month, auto-detects Node apps, German data centers) or GitHub Actions plus a container registry (free but requires setup).

What You'll Need Before Deploying

A working local app. GitHub account and Git installed. A deployment platform choice. You do not need DevOps experience.

Your app is ready if it has package.json and listens on a port--typically 3000, 5000, or 8080. Some Cursor apps include a build step that compiles TypeScript or JSX; others ship as-is.

Deployment platforms differ in philosophy. Some require you to write and test a Dockerfile locally first. Others auto-detect your app type and build on their servers. Ship auto-detects Node.js, Python, or Go apps and constructs the Dockerfile in the cloud without you writing anything--though you can provide one if you want control.

Create a free GitHub account at github.com if you don't already have one. All platforms here integrate with GitHub for automatic deploy-on-push.

Step 1: Prepare Your App for Deployment

Make sure your app listens on the PORT environment variable or defaults to 3000. Test locally with npm start and verify your app responds on localhost port 3000.

Cursor generates a production Dockerfile in seconds. Open your project in Cursor, create a file called Dockerfile in the root directory, then use Ctrl+I (Cmd+I on Mac) to open the inline edit tool. Type this prompt: "Write a Node.js Dockerfile for production that uses a multi-stage build and Alpine base." Cursor generates the complete file.

Test the Dockerfile locally before pushing. Run docker build -t my-app. && docker run -p 3000:8080 my-app:latest. Visit localhost port 8080 to verify it responds.

Add environment variables to your.env file if your app needs them for database URLs or API keys. Create a.env.example file documenting the keys (no values) as a reference. Add.env to.gitignore and never commit secrets. Most deployment platforms provide a UI or API to inject environment variables at deploy time, keeping secrets out of your repository.

Step 2: Push Your Code to GitHub

Git is version control; GitHub is where your code lives in the cloud. Initialize Git in your project, commit your code, add your GitHub repository as a remote, and push. Your deployment platform watches this repository and auto-deploys on every push.

Workflow:

1. Go to github.com, click "New repository", name it (e.g., "my-cursor-app"), and create it.
2. In your terminal, run git init.
3. Add your code: git add..
4. Commit: git commit -m "Initial commit".
5. Add the remote: git remote add origin and paste your repository's clone URL from GitHub.
6. Push: git push -u origin main (or master, depending on your default branch).

GitHub prompts for credentials if SSH is not configured yet. If you already have a Dockerfile, commit it. If not, platforms like Ship auto-detect Node.js and generate the Dockerfile on-the-fly--you can skip creating one and let the platform handle it.

Deployment Platform Options: Picking the Right Fit

Deployment platforms fall into three categories: managed GitOps platforms (Northflank, Render, Railway, Ship) that handle builds and infrastructure; GitHub Actions plus container registry (free, DIY); and self-hosted solutions (Dokploy, Coolify) running on your own VPS.

Option A: GitOps Platforms

Northflank, Render, Railway, and Ship all work the same way: watch your GitHub repo, auto-detect your app type, build a container, and deploy to their infrastructure. No server provisioning, no Dockerfile writing required (unless you want to).

Northflank and Render start around EUR 5-10/month for a small Node app and scale with compute and traffic. Northflank tends to cost more but offers advanced features like preview environments for pull requests and custom domain setup. Railway charges per resource-second, cheaper for hobby projects but pricing becomes unpredictable as traffic spikes. Ship charges a flat rate of EUR 10-20/month, eliminating surprise charges. All three offer free trials.

Setup is fast: create an account, connect your GitHub repo via OAuth, and the platform auto-deploys on the first push. No Dockerfile needed; the platform detects Node.js and configures itself. If your app needs environment variables (database URL, API keys, third-party tokens), you provide them via the platform's dashboard, and they are injected at runtime.

Best for: Teams wanting simplicity and predictability. Ship's flat rate appeals to founders who fear unpredictable bills. Northflank suits teams needing preview environments and advanced deployment controls. See the Ship documentation on deploying apps built with AI agents for Cursor-specific workflows.

Option B: GitHub Actions + Container Registry

This is the most DIY route. GitHub Actions (built into GitHub, free for public repos) builds your Dockerfile and pushes the container to a registry (GitHub Container Registry, Docker Hub). You then point a cloud container service (AWS Elastic Container Service, Google Cloud Run, Azure Container Instances) at that registry.

You write a GitHub Actions workflow--a YAML file--that runs on every push. The workflow builds your Dockerfile, tags the image, and pushes it to the registry. A separate service watches the registry and deploys new images.

Cost: GitHub Actions is free for public repositories. Docker Hub storage is free. Cloud container platforms offer generous free tiers but charge per request and compute.

Setup: 30-45 minutes if you know YAML; longer if you don't. Writing the workflow is error-prone. Debugging a broken workflow consumes time.

Best for: Builders who like control, have time for troubleshooting, and enjoy complexity. If you prefer a platform managing the infrastructure, GitOps is simpler.

Option C: Self-Hosted (Dokploy, Coolify)

Run your own platform using Dokploy or Coolify, both open-source projects mimicking Heroku. Install on a VPS (Hetzner, Linode, DigitalOcean, AWS), connect your GitHub repo, and deploy via a web UI.

Cost: VPS only, typically EUR 5-20/month. Hetzner is particularly cheap. No platform markup.

Setup: 1-2 hours. Provision a server, SSH into it, install Dokploy or Coolify, add your GitHub repo. The platform handles the rest.

Best for: Builders who want the lowest cost and are comfortable with server management. Trade-off: you handle backups, security updates, and manual scaling. Outages are your problem to fix.

Deploying on Ship

Ship is Opsily's managed platform designed for Cursor-built apps. It charges a flat rate of EUR 10-20/month, auto-detects your app type (Node.js, Python, or Go), builds and deploys without requiring a Dockerfile, and runs on German data centers with GDPR compliance built-in.

Steps:

1. Go to console.opsily.com and create an account.
2. Click "New Project", select "Git Deploy", and authorize GitHub access.
3. Choose your repository and branch (usually main).
4. Ship auto-detects your app as Node.js. If prompted for a build command, enter npm run build or skip if your app runs as-is.
5. Add environment variables if your app needs them (database URL, API keys, etc.) in the "Environment" section of the Ship dashboard.
6. Click "Deploy". Ship builds your Dockerfile in the cloud and deploys. You get a live URL in 2-5 minutes.

The key advantage of Ship's flat-rate pricing: your bill stays the same whether you get 100 visitors or 10,000 per month (within fair-use limits). This eliminates surprise charges that plague pay-per-resource platforms. For solo founders and early-stage startups, this predictability is valuable.

Ship also provides preview environments for pull requests. Every time you open a pull request, Ship creates a temporary deployment with a unique URL. This lets you and collaborators test changes before merging to main. For more on how Ship integrates with Cursor workflows, see the guide on deploying apps built with AI agents.

Common Gotchas & Debugging

Build failures usually stem from missing environment variables, Node.js version mismatches, or your app listening on a hardcoded port instead of the PORT environment variable.

Node.js version mismatch: Your local machine runs Node 18, but Ship defaults to Node 16. Add a.nvmrc file to your repository root with the line 18.0.0. Ship respects it and builds with that version. Push and redeploy.

App crashes with missing environment variable: Your app accesses process.env.DATABASE_URL but the variable is not set. Add it in your deployment platform's dashboard under "Environment Variables" or "Secrets". Redeploy.

App listens on hardcoded port: Your code has server.listen(3000) instead of using the PORT environment variable. Edit your server file to use const port = process.env.PORT || 3000;. Push and redeploy.

Database queries fail after deploy: Your database runs locally on your machine but is not deployed to the cloud. You need a managed database service. Ship, Render, and Northflank offer PostgreSQL or MySQL integrations. Alternatively, use Supabase (PostgreSQL) or Planetscale (MySQL) outside your platform. Provision the database, get its connection string, add it as an environment variable, and redeploy.

Slow or timeout builds: Large node_modules or unnecessary build artifacts slow builds. Ensure your.dockerignore file excludes node_modules,.git, and build outputs. Check that your build command is not creating massive artifacts.

Check your platform's logs immediately after a deployment failure. Most platforms display real-time build output and runtime errors in the dashboard. The error message usually pinpoints the issue.

After Deployment: What's Next?

Your app is live. Now set up monitoring, custom domains, and optional features like preview environments and database backups.

Monitoring: Check your deployment platform's logs daily for the first week. Most platforms display real-time logs in the dashboard. Look for repeated errors or warnings.

Custom domain: Most platforms let you add a custom domain (yourapp.com instead of platform-generated URL). Verify ownership via CNAME, and the platform handles TLS (HTTPS) automatically.

Database: If your app uses a database, provision one now. Ship, Render, and Northflank offer PostgreSQL or MySQL. Add the connection string as an environment variable. Run any migrations (e.g., knex migrate:latest) if needed.

Preview environments: For teams or code review workflows, set up preview deployments for pull requests. Ship and Northflank support this out-of-the-box, creating a unique URL for each PR.

Keep iterating: Your deployment environment does not replace Cursor. Continue building features in Cursor, push changes to GitHub, and your platform auto-deploys. The workflow is: code in Cursor git push auto-deploy live. Before announcing your app to customers, check the pre-launch checklist for security and reliability best practices.

Frequently Asked Questions

Do I need to stop using Cursor once I deploy?

No. Cursor is your development environment; your deployment platform is where your app runs in production. You continue writing code in Cursor, commit and push to GitHub, and the platform auto-deploys on every push. Your workflow stays the same.

Do I have to use a Dockerfile?

No. Many platforms auto-detect your app type. Ship, Render, and Northflank all support auto-detection. You only need a Dockerfile if you want fine-grained control over the build process or if your app uses a language (Go, Rust, Elixir) that requires explicit configuration.

My app runs locally but fails when I deploy it. Why?

Most common reasons: missing environment variables, hardcoded ports, or a database running locally but not in the cloud. Test locally with npm start and check your app's response. Then check your deployment platform's logs for the exact error. Common fixes: add PORT environment variable to your server code, add DATABASE_URL to the platform dashboard, or provision a managed database.

Can I add a database to my Cursor app?

Yes. Most platforms offer PostgreSQL or MySQL. Provision it in the platform dashboard, get the connection string, add it as an environment variable, and reconnect your app. If you prefer a managed service outside your platform, Supabase (PostgreSQL) and Planetscale (MySQL) integrate easily.

What happens if my app gets a traffic spike?

GitOps platforms like Northflank, Render, and Ship auto-scale compute to handle traffic spikes. GitHub Actions plus DIY setups do not; you pay per request and may hit rate limits. Self-hosted solutions need manual scaling. Ship's flat rate covers reasonable traffic spikes within fair-use.

How do I debug a failed deployment?

Check your platform's logs immediately after build or deploy fails. Most platforms display build output and runtime errors in the dashboard. If the build fails, look for Node version mismatches or missing build scripts. If the app starts but crashes, the runtime error in logs usually pinpoints the issue.

The Bottom Line

Deploying a Cursor-built app takes minutes if you choose the right platform. Containerize, push to GitHub, pick a platform, and you are done. GitOps platforms are simple and auto-scale; GitHub Actions is free but complex; self-hosted is cheapest but demands ops work.

Ship's flat rate (EUR 10-20/month) makes it the simplest choice for solo founders who want predictability and no surprise bills. Before going public, check the pre-launch checklist to confirm your app is production-ready.