Skip to content

Dev setup

Jump to bottom
Jonathan Sharpe edited this page Aug 24, 2024 · 30 revisions

Requirements

You need Node (^20.9 || ^22) and npm (^10) installed to use this starter kit. It's tested with the active and maintenance LTS versions of Node.

You can check your current versions of these tools with node --version and npm --version.

OS

The automated testing all takes place in Ubuntu and Windows Server, but other Linux versions and macOS should work too.

Installation

  1. Clone your repository to your local machine.

  2. cd into the repository's directory on your local machine. You can run git status to check you're in the right place, it should say something like

    On branch main
Your branch is up to date with 'origin/main'.

nothing to commit, working tree clean

  3. Install the dependencies by running npm ci (or npm install); this will create a node_modules/ directory and fill it with the requirements specified in the various package.json files and package-lock.json.

  4. Set up a database and configure the app to connect to it, see Dev setup#Database

    Note: even if you've deployed to Render or similar, I'd suggest setting up a separate database for local development (otherwise any errors or experiments in your local development can impact your production deployment and the rest of your team).

  5. Create a .env file in the root of the repository for any environment variables you'll need (see Dotenv). Start by setting your DB connection string and enabling extra logging to help develop and debug:

    DATABASE_URL=<...>
LOG_LEVEL=debug

  6. Run the app using either npm run dev (developer mode, with watching/reloading of your code as you make changes) or npm run serve (production mode, to check what will actually get deployed) - see Scripts for more details.

  7. While one of those two scripts is running, visit http://localhost:3000 to see the app.

    Screenshot 2024-08-24 at 09 55 32

    If you see any errors, or the site doesn't look like the image above, check out Home#Common errors.

  8. Now that you're up and running, see Structure to get an idea of the layout of the kit and where to start putting your code.

Database

You'll need to supply a database for the app to use on startup. The app tries to connect to the database specified by the DATABASE_URL environment variable (which e.g. Heroku sets automatically).

This variable can be set in the .env file in the repository root, see Dotenv. You can see configuration and connection data (or edit it if needed) in api/db.js and api/utils/config.js.

⚠️ Do not include credentials (usernames, passwords, etc.) in your source code. Store them only in .env, which is excluded from git tracking, for local development, and look up how to set real environment variables in your deployment environment (e.g. Heroku, Render, ...) for production.

To run Postgres locally, see:

  • Official installer: follow the instructions at https://www.postgresql.org/download/

  • Homebrew (macOS only): brew install postgresql then brew services start postgresql

  • Docker: assuming you've installed Docker, see https://docs.docker.com/get-docker/:

    docker run --detach --env POSTGRES_DB=<db> --env POSTGRES_PASSWORD=<password> --name <name> --publish 5432:5432 postgres

    The database URL will be postgres://postgres:<password>@localhost:5432/<db>

    You can start and stop the container as needed using docker stop <name>/docker start <name>.

Once you have Postgres up and running, unless you used Docker, createdb <db> to create the database the app will use.

Ports

If you see EADDRINUSE when trying to run dev or serve, you may have other processes running on your machine that are using ports the starter kit expects. You can check which processes these are using the command:

lsof -i :<port>

If you see existing npm commands running, you may have terminals running in the background somewhere - find them and stop them! If you see some other program running, you may need to switch ports. You can do this as follows:

  • npm run dev:
    • Frontend (default: 3000): you need to change the line "dev:web": "cross-env PORT=3000 npm --workspace web run dev", in package.json
    • Backend (default: 3100): you need to change the line "dev": "cross-env API_PORT=3100 concurrently \"npm:dev:*\"", in package.json.
  • npm run serve:
    • Backend (default: 3000): the easiest way to override this is when you actually run the server, so you can do e.g. PORT=3210 npm run serve. Alternatively you can change the line port: parseInt(process.env.PORT ?? "3000", 10), in api/utils/config.js.
Clone this wiki locally