Run your project locally first

The slowest way to find a bug is to deploy, watch the server crash, fix, deploy again. The fastest is to run your project on your own computer first, where changes are instant and nothing is live. This guide gets your project running locally and mirrors the one Falix-specific detail — the port — so "works on my machine" also means "works on the server".

1. Install the runtime locally

Install the same language your Falix application uses, from its official source:

• Node.js — download the LTS build from nodejs.org. Check it worked: node -v and npm -v.
• Python — download from python.org. Check it worked: python --version (or python3 --version) and pip --version.

💡 Tip: Match the version to your server. Falix lets you pick the Node or Python version on the Settings page; install the same major version locally so a feature that works on your machine also works on the server. See Node.js on Falix and Python on Falix.

2. Get your code onto your machine

Clone the repository you push to (the Git from zero guide covers this):

git clone https://github.com/you/my-project.git
cd my-project

3. Install dependencies locally

This mirrors exactly what Falix does automatically when your server starts:

# Node — reads package.json
npm install

# Python — a virtual environment keeps things tidy, then install
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt

On Falix these run for you on every start; locally you run them once (and again whenever the dependency list changes).

4. Handle the port — the one thing that differs

On a Falix server your public port arrives as the environment variable SERVER_PORT, and your app is written to read it:

const PORT = process.env.SERVER_PORT || 8080;
server.listen(PORT, '0.0.0.0', () => console.log(`Listening on ${PORT}`));

On your own machine, SERVER_PORT isn't set, so that code falls back to 8080 — which is fine. But to run exactly the way the server does, set the variable yourself when you launch:

# macOS / Linux
SERVER_PORT=3000 node index.js

# Windows PowerShell
$env:SERVER_PORT=3000; node index.js

Then open http://localhost:3000 in your browser. (Locally, binding 0.0.0.0 also answers on localhost — same code, no changes needed.)

🎯 Good to know: Prefer a file over typing the variable each time? A .env file plus a loader (dotenv for Node, python-dotenv for Python) reads SERVER_PORT=3000 at startup. Keep .env out of Git — it's for local and server secrets, never the repo. See Keep secrets out of Git.

5. The loop

With the runtime installed and the port sorted, you've got a tight feedback cycle:

You go around the first three steps many times, cheaply, and only push when it works. The deploy is the last step, not the debugger.

What not to commit

Generated and machine-specific files don't belong in Git — they're rebuilt on the server anyway. Add these to .gitignore:

• node_modules/ (Node) and .venv/ / __pycache__/ (Python) — reinstalled from package.json / requirements.txt on start.
• .env — secrets live on the server, not in the repo.
• Local databases, build output, and log files.

The honest caveat: local isn't identical to Falix

Your laptop and a Falix container are not the same machine. Keep these differences in mind so a green run locally doesn't surprise you on deploy:

• OS and versions — match your Node/Python major version to the server's; a newer local version can run code the server's version can't.
• Managed databases and Redis run as Falix services with their own host/port and credentials — locally you point at a local database or a throwaway one, using the same connection string shape. See Add a database.
• The session timer and resources — free servers have 2.5 GB shared RAM and a session timer; your laptop probably has more room. Test memory-hungry code with the server's limits in mind. See Keeping apps online.

Verify it works

Run your app locally with SERVER_PORT set and open http://localhost:3000 (or watch a bot connect in your terminal). Seeing your app behave on your machine — before any deploy — is the whole win. Then push, and the server runs the code you already know works.

Troubleshooting

• command not found: node / python — the runtime didn't install onto your PATH; reinstall from the official installer and reopen your terminal.
• App runs locally but the browser page is blank — you opened the wrong port; use the one you set in SERVER_PORT (http://localhost:3000 above).
• Works locally, fails on Falix with "Cannot find module" — a dependency is installed locally but missing from package.json / requirements.txt. Add it and push. See My app won't start.
• Different behaviour on the server — check your local runtime version matches the server's on the Settings page.

Next steps

• Your first test suite
• Deploy from Git
• Runtime downloads and docs: nodejs.org and python.org