Deploy Your First App — Complete Walkthrough

This guide takes you from an empty folder on your own computer to a live website, in about ten minutes. No previous deployment experience is needed.

Every command below was run exactly as written before this guide was published.

If you already have an application and just want the deploy command, see Deploying with a Deploy Token instead.

What you need before you start

Windows: use PowerShell, not the old Command Prompt. tar and curl are included in Windows 10 and 11.

You do not need Git, Docker, or an SSH key.

This guide uses Node.js because it needs no installation beyond Node itself. The same steps work for Python, Go, Ruby, PHP, Java, Rust and .NET — the Python equivalent is shown at each step.

Step 1 — Create the project folder

mkdir hello-app
cd hello-app

Step 2 — Write the application

Create three small files in that folder.

`index.js` — the application itself:

const http = require('http');

// The platform tells your app which port to listen on.
// Locally there is no PORT, so fall back to 3000.
const port = process.env.PORT || 3000;

const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
  res.end('<h1>Hello from App Platform</h1><p>My first deployment.</p>');
});

// 0.0.0.0 means "accept connections from outside this container".
server.listen(port, '0.0.0.0', () => {
  console.log(`Listening on port ${port}`);
});

`package.json` — tells the platform this is a Node.js project:

{
  "name": "hello-app",
  "version": "1.0.0",
  "private": true,
  "scripts": {
    "start": "node index.js"
  }
}

`Procfile` — tells the platform how to start it. No file extension:

web: node index.js

That is the whole application. Three files, no dependencies to install.

Step 3 — The two rules that decide whether your app works

Almost every "the build succeeded but my site does not load" report comes down to one of these two lines. They matter more than anything else in this guide.

Rule 1 — listen on the port the platform gives you. Your app must read the PORT environment variable. Do not hardcode a port number.

Rule 2 — bind to `0.0.0.0`, not `localhost`. An app bound to localhost only accepts connections from inside its own container, so the outside world sees nothing.

server.listen(3000, 'localhost');              // ✗ unreachable
server.listen(process.env.PORT, '0.0.0.0');    // ✓ correct

The Python equivalent:

import os
port = int(os.environ.get('PORT', 5000))
app.run(host='0.0.0.0', port=port)             # ✓ correct

Step 4 — Run it on your own machine first

Always confirm the app works locally before deploying. If it does not run here, it will not run on the platform, and you will spend far longer debugging it there.

PORT=3000 node index.js

You should see:

Listening on port 3000

Open http://localhost:3000 in your browser. You should see Hello from App Platform.

Stop the server with Ctrl+C.

On Windows PowerShell, set the variable separately:

```powershell

$env:PORT=3000; node index.js

```

Step 5 — Create the app in your Client Portal

1. Sign in to your Client Portal
2. Go to Services → App Platform
3. Click New App and give it a name
4. Open the app — its address is shown on the Overview tab

If your plan still has room, the app is created immediately. Nothing extra to buy.

Step 6 — Create a deploy token

1. In your app, open the Deploy Tokens tab
2. Click Create Token and name it (for example laptop)

The page then shows a ready-to-run command with your new token already in it. Copy that — it saves you editing anything by hand.

The token is shown only once. We store only a hash of it, so it cannot be shown again or recovered. If you lose it, delete that token and create another.

Step 7 — Package and deploy

Move up one level, so you are in the folder that contains hello-app, and package it:

cd ..
tar czf app.tar.gz -C hello-app .

The -C hello-app . part means "package the contents of hello-app", not the folder itself. That matters: the platform expects to find package.json at the top of the archive.

Then upload it. If you copied the ready-made command in Step 6, paste it now. Otherwise replace <YOUR_DEPLOY_TOKEN> and the app name:

curl -X POST https://deploy.colosoft.com/deploy/your-app-name \
  -H "Authorization: Bearer <YOUR_DEPLOY_TOKEN>" \
  -H "Content-Type: application/gzip" \
  --data-binary @app.tar.gz

The command waits while your app is built — around 45 seconds for a small app. It then returns the build result.

Do not include `node_modules` in the archive. The platform installs your dependencies itself, and shipping them makes the upload far larger and the build slower. If your project has one, exclude it:

```bash

tar czf app.tar.gz --exclude=node_modules --exclude=.git -C hello-app .

```

Step 8 — What happens during the build

1. Your archive is received
2. The language is detected — package.json means Node.js
3. Dependencies are installed
4. The application is built
5. A health check runs
6. Traffic switches to the new version with no downtime

You can follow the output live on the Deploys tab.

Step 9 — Open your live site

Go to the Overview tab and click your app's address. You should see Hello from App Platform.

Your site is live, with HTTPS already set up.

Step 10 — Change something and deploy again

This is the loop you will use from now on. Edit index.js:

res.end('<h1>Hello from App Platform</h1><p>Updated!</p>');

Then repeat the two commands from Step 7 — package, upload. Refresh your site and the change is there.

If something goes wrong

See Troubleshooting App Platform for more.

Next steps

• Store settings and secrets → Environment Variables
• Add a database → PostgreSQL Database
• Use your own domain name → Custom Domains & SSL
• Deploy automatically on every push → GitHub Auto-Deploy