Local Development Setup Guide: Portable, Fast and Isolated Environments

· Canvasly Web Studio · Development · 10 min read

A new laptop running one setup command for a portable, isolated local development environment

"It works on my machine" is the most expensive sentence in software. It means a bug that only shows up for one person, a new developer who loses their first week to setup, or a release that breaks because production runs a different version than your laptop. A good local development environment fixes all three. It's portable (it runs the same on every machine), fast (it doesn't slow you down), and isolated (projects don't interfere with each other or with your computer). Here's how to build one.

If setting up a project takes more than one command, it’s not documented, it’s folklore.

  • Portable: the same result on every machine.
  • Fast: it never slows you down.
  • Isolated: projects can’t break each other, or your computer.

The goal

The five layers of a local setup

Every project's local environment is made of the same five layers. The secret of a portable setup is simple: write each layer down in the repository, so a new machine can rebuild it with one command.

The five layers: runtimes, dependencies, services, configuration and commands

Let's go through them one by one.

1. Pin your runtime versions

Different projects need different versions of Node.js, Python, PHP or Ruby. Installing one global version for everything guarantees conflicts sooner or later.

Use a version manager that reads the version from a file in the project, and switches automatically when you enter the folder:

# mise.toml (in the project root)
[tools]
node = "22"
python = "3.12"
mise install        # installs exactly these versions
node --version      # v22.x inside this folder, whatever the rest of the machine uses

Commit the version file (mise.toml, .tool-versions or .nvmrc), and make your CI use the same file. Local and CI now run the same runtime.

2. Lock your dependencies

Version ranges such as ^4.2 mean two developers can install two different versions on the same day. Commit the lockfile and install from it:

Ecosystem Lockfile Install exactly what's locked
npm package-lock.json npm ci
pnpm pnpm-lock.yaml pnpm install --frozen-lockfile
Python (uv) uv.lock uv sync --frozen
PHP (Composer) composer.lock composer install

Use the "frozen" install in CI and in your setup script. Only update the lockfile on purpose, in its own commit.

3. Run services in containers

Databases, caches and mail servers are where machines differ most, and where "just install it with Homebrew" leads to three projects fighting over one PostgreSQL. Run them in Docker Compose instead: one file, exact versions, and nothing installed on your computer.

# compose.yaml
services:
  db:
    image: postgres:16
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: app
      POSTGRES_DB: app
    ports:
      - "127.0.0.1:5432:5432"   # only reachable from this machine
    volumes:
      - db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app"]
      interval: 2s
      retries: 15

  redis:
    image: redis:7
    ports:
      - "127.0.0.1:6379:6379"

  mail:
    image: axllent/mailpit       # catches every email your app sends
    ports:
      - "127.0.0.1:8025:8025"    # web inbox
      - "127.0.0.1:1025:1025"    # SMTP for your app

volumes:
  db-data:
docker compose up -d --wait   # start everything, wait until the database is healthy
docker compose down           # stop (data stays in the volume)
docker compose down -v        # stop and wipe the data: a clean slate

A few habits make containers safer and easier:

Should the app itself run in a container?

Not always. Running the services in containers and the app directly on your machine is often the fastest combination, especially on macOS, where file sharing between the host and containers is slower. Run the app in a container too when you need an exact match with production's operating system, or when the tooling is hard to install natively.

4. Want full isolation? Use a Dev Container

A Dev Container puts the whole development environment (runtimes, tools, editor extensions and services) inside containers, described by one file. VS Code, Cursor, JetBrains IDEs and GitHub Codespaces can all open it.

// .devcontainer/devcontainer.json
{
  "name": "shop",
  "image": "mcr.microsoft.com/devcontainers/javascript-node:22",
  "forwardPorts": [3000],
  "postCreateCommand": "npm ci",
  "customizations": {
    "vscode": { "extensions": ["dbaeumer.vscode-eslint", "esbenp.prettier-vscode"] }
  }
}

Open the folder, choose Reopen in Container, and a new team member has a working environment without installing anything but Docker and an editor. The same file runs in the cloud with Codespaces, which is handy for reviews and for working from a tablet.

Install Docker and an editor, open the folder, and start working. Everything else is described in the repository.

The Dev Container promise

5. Handle configuration and secrets safely

Settings that change between machines (database address, API keys, feature flags) belong in environment variables, not in the code.

# .env.example (committed)
DATABASE_URL=postgres://app:app@127.0.0.1:5432/app
REDIS_URL=redis://127.0.0.1:6379
SMTP_HOST=127.0.0.1
SMTP_PORT=1025
STRIPE_SECRET_KEY=sk_test_replace_me

6. Local domains and HTTPS

Many things behave differently on http://localhost:3000 than in production: secure cookies, OAuth redirects, service workers, mixed-content rules. A local domain with HTTPS removes the surprises.

mkcert -install                 # once per machine: trust the local certificate authority
mkcert shop.localhost           # creates shop.localhost.pem and shop.localhost-key.pem

Point your dev server or a local proxy (Caddy, Traefik, nginx) at those files.

7. One command for everything

The best documentation is a command that works. Put the common tasks behind short, memorable names, with a Makefile, a justfile or package.json scripts:

# Makefile
setup:            ## first run on a new machine
    mise install
    cp -n .env.example .env || true
    npm ci
    docker compose up -d --wait
    npm run db:migrate && npm run db:seed

dev:              ## start everything
    docker compose up -d --wait
    npm run dev

test:             ## same checks as CI
    npm run lint && npm test

reset:            ## back to a clean database
    docker compose down -v
    docker compose up -d --wait
    npm run db:migrate && npm run db:seed

Now the README can be four lines long: clone, make setup, make dev, open the URL.

Realistic data, without real people

Seed scripts and fixtures give everyone the same starting data. If you need production-like volumes, use an anonymised snapshot: replace names, emails, addresses and payment details before the data leaves production. Never copy real customer data to a laptop.

Make it fast

A portable setup is only useful if people enjoy using it:

Keep it consistent

Your local environment should be the most boring part of your day: same versions, same commands, same results, everywhere.

Consistency wins

AI assistants in your local environment

AI coding assistants work best with a local setup they can understand: clear commands, a seeded database and tests they can run. Keep them safe:

Where Canvasly Web Studio fits

Canvasly Web Studio follows the same principles for the design side of a project:

The new-laptop test

The best way to check your setup is to try it fresh, on a new machine, a new user account, or a Codespace:

  1. Can you go from git clone to a running app with one or two commands?
  2. Does it take under ten minutes, without asking anyone for help?
  3. Are runtime versions, dependencies and services all pinned in the repository?
  4. Is there a .env.example, and are no secrets committed?
  5. Can you reset to a clean database in one command?
  6. Do tests run the same way locally and in CI?
  7. Are ports bound to 127.0.0.1 and test emails caught locally?

If you can answer "yes" to all seven, you've built a local environment your team will thank you for.

Conclusion

A great local environment isn't about one perfect tool. It's about writing every layer down: pinned runtimes, locked dependencies, services in containers, safe configuration, and one command to run it all. Do that, and "it works on my machine" becomes "it works on every machine", including the one that runs production.

Designing the website part of your project? Try Canvasly Web Studio free for 7 days at canvasly.pro.

Related reading: Database performance tuning 101 · Minimalist web stack vs. heavy page builders