devsetup.mdoc

---
title: Development setup
description: How to set up Mercury Core for local development.
---

This guide details how to set up Mercury Core for local development and modification.

For a guide on server installation and hosting for production, see [Production setup](/guides/prodsetup).

## Requirements

You should already have the necessary dependencies and command line tools installed. If not, see [Installation](/install) for an installation guide.

You will need:

- Latest version of [Git](https://git-scm.com) installed (expected as `git`, optional)
- Latest version of [Bun](https://bun.sh) installed (expected as `bun`, [installation guide](/install/bun))
- Latest version of [Go](https://go.dev) installed (expected as `go`, [installation guide](/install/go))
- Latest version of [SurrealDB](https://surrealdb.com) installed (expected as `surreal`, [installation guide](/install/surrealdb))
- A terminal
- A modern web browser (Early 2024 onwards for most major browsers)
- A computer, as it would be painful to live without one, wouldn't it?

If you wish to use containers instead of SurrealDB and Go, install the latest version of a container manager such as [Docker](https://www.docker.com) (expected as `docker`, [installation guide](/install/docker)) or an alternative container manager like [Podman](https://podman.io) ([installation guide](/install/podman)).

## Instructions

{% steps %}

1. Clone the [tp-link-extender/MercuryCore](https://github.com/tp-link-extender/MercuryCore) repository to a directory of your choice on your local machine, and navigate to the root directory of the repository.

	```bash
	git clone https://github.com/tp-link-extender/MercuryCore
	cd MercuryCore
	```

   - If not using Git, you can also [download the repository as a compressed archive file](https://github.com/tp-link-extender/MercuryCore/archive/refs/heads/main.zip) (.zip) from the GitHub page and extract it to a directory of your choice.

2. If not using containers, navigate to the **Economy** directory, and run `go build` to compile the Economy service.

3. Navigate to the **Site** directory, and run `bun i` to install all dependencies.

4. Copy the **Site/.env.example** file to **Site/.env** and modify it to set up the environment variables.

5. If using containers, run `docker compose up -d` to start the Database and Economy services.

6. Run `bun dev` to start the development server and open the web interface in your default browser. This will start the Database and Economy services automatically if they are not already running.
	{% aside type="tip" title="Hot reloading" %}
		The development server supports hot reloading, so any changes you make to the code will be automatically reflected in the browser without needing to refresh the page.
	{% /aside %}

{% /steps %}

After following these steps, you should have a local development server set up for Mercury Core. More information on the development server is available on the [Site service page](/services/site).

## Common issues

### Filesystem permissions

In some cases, the development server may fail to start due to filesystem permission issues. This can occur if the user running the development server does not have the necessary permissions to read or write to files or directories where dependencies are installed.

An example of potential output could be as follows:

```
error when starting dev server:
Error: EACCES: permission denied
    at writeFileSync (unknown)
    at write (~/MercuryCore/Site/node_modules/@sveltejs/kit/src/core/sync/utils.js:29:5)
    at write_if_changed (~/MercuryCore/Site/node_modules/@sveltejs/kit/src/core/sync/utils.js:18:3)
    at write_tsconfig (~/MercuryCore/Site/node_modules/@sveltejs/kit/src/core/sync/write_tsconfig.js:47:2)
    at init (~/MercuryCore/Site/node_modules/@sveltejs/kit/src/core/sync/sync.js:17:2)
    at dev (~/MercuryCore/Site/node_modules/@sveltejs/kit/src/exports/vite/dev/index.js:58:7)
    at configureServer (~/MercuryCore/Site/node_modules/@sveltejs/kit/src/exports/vite/index.js:968:17)
    at _createServer (~/MercuryCore/Site/node_modules/vite/dist/node/chunks/node.js:26529:97)
    at async <anonymous> (~/MercuryCore/Site/node_modules/vite/dist/node/cli.js:572:24)
    at processTicksAndRejections (native:7:39)
error: script "dev" exited with code 1
```

### Hot reloading

If you are using WSL2 on Windows, the server may not correctly reflect the changes you make if the repository is stored on the Windows drive. To fix this, move the repository into a folder managed by WSL, or alternatively add the following to the default export of the **vite.config.ts** configuration file:

```ts
server: { watch: { usePolling: true } },
```