Run your project locally first

Intermediate 168 4 min read

Install Node or Python on your own machine, run your app before you deploy, mirror SERVER_PORT with a local env var, and settle into the edit-locally, push, deploy loop.

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".

At a glance
You need	Your project in a Git repo, and admin rights to install software on your computer
Plan	Any — this runs on your machine, not a server
Time	Thirty minutes the first time

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:

Step	Where	Command
Edit	Your machine	Your editor
Run	Your machine	`node index.js` / `python app.py`
Check	Your machine	Browser, console output, tests
Commit & push	Your machine	`git add . && git commit -m "…" && git push`
Deploy	Falix	Auto-deploy fires, or press Deploy

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

Was this guide helpful?

More in this category

Git from zeroBeginner 164 Branches without fearBeginner 177 Where to edit your codeBeginner 249 Your first test suiteIntermediate 150 Logging that helps at 3amIntermediate 172

View all

Run your project locally first

Intermediate 168 4 min read

Install Node or Python on your own machine, run your app before you deploy, mirror SERVER_PORT with a local env var, and settle into the edit-locally, push, deploy loop.

At a glance
You need	Your project in a Git repo, and admin rights to install software on your computer
Plan	Any — this runs on your machine, not a server
Time	Thirty minutes the first time

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:

Step	Where	Command
Edit	Your machine	Your editor
Run	Your machine	`node index.js` / `python app.py`
Check	Your machine	Browser, console output, tests
Commit & push	Your machine	`git add . && git commit -m "…" && git push`
Deploy	Falix	Auto-deploy fires, or press Deploy

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

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

Was this guide helpful?

More in this category

Git from zeroBeginner 164 Branches without fearBeginner 177 Where to edit your codeBeginner 249 Your first test suiteIntermediate 150 Logging that helps at 3amIntermediate 172

View all

Run your project locally first

1. Install the runtime locally

2. Get your code onto your machine

3. Install dependencies locally

4. Handle the port — the one thing that differs

5. The loop

What not to commit

The honest caveat: local isn't identical to Falix

Verify it works

Troubleshooting

Next steps

Falix Guides

Browse by topic

Only show guides for your app

Run your project locally first

1. Install the runtime locally

2. Get your code onto your machine

3. Install dependencies locally

4. Handle the port — the one thing that differs

5. The loop

What not to commit

The honest caveat: local isn't identical to Falix

Verify it works

Troubleshooting

Next steps