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 | You need | How to check | If it is missing | |----------|--------------|------------------| | Node.js | `node --version` | Download from nodejs.org (any version 18 or newer) | | A terminal | Terminal on macOS/Linux, PowerShell on Windows | Already installed | | `tar` and `curl` | `tar --version` and `curl --version` | Built in on macOS, Linux and Windows 10+ | | An App Platform plan | Client Portal → **Services → App Platform** | See *Plans, Apps and Limits* | > **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 ```bash mkdir hello-app cd hello-app ``` ## Step 2 — Write the application Create three small files in that folder. **`index.js`** — the application itself: ```javascript 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('

Hello from App Platform

My first deployment.

'); }); // 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: ```json { "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. ```javascript server.listen(3000, 'localhost'); // ✗ unreachable server.listen(process.env.PORT, '0.0.0.0'); // ✓ correct ``` The Python equivalent: ```python 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. ```bash 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: ```bash 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 `` and the app name: ```bash curl -X POST https://deploy.colosoft.com/deploy/your-app-name \ -H "Authorization: Bearer " \ -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`: ```javascript res.end('

Hello from App Platform

Updated!

'); ``` Then repeat the two commands from Step 7 — package, upload. Refresh your site and the change is there. ## If something goes wrong | What you see | What it means | |--------------|---------------| | `Missing Authorization: Bearer ` | The `-H "Authorization: ..."` line is missing from your command | | `Invalid or expired deploy token` (401) | Three possible causes: the token is wrong, expired or deleted; you pasted the command **without replacing ``**; or the app name in the URL is not the app this token belongs to. A token works for one app only, so a wrong app name also reports an invalid token | | `413` | The archive is over 512 MB. Exclude `node_modules` and any large files | | Build fails | The upload worked; this is a build problem. Open the **Deploys** tab for the log | | Build succeeds but the site does not load | Almost always Rule 2 in Step 3 — check you bind to `0.0.0.0` and read `PORT` | 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*