6 Developer setup

Kailash Nadh edited this page 2020-03-12 10:17:01 +05:30

Table of Contents

• First time setup
• Running the dev environment
• Configuring with environment variables
• Dev proxy
• Setup an Nginx proxy endpoint
• Production build

There are two distinct components, the Go backend and the React frontend. In the dev environment, both are run independently.

First time setup

git clone https://github.com/knadh/listmonk.git. The project uses go.mod, so it's best to clone it outside the Go src path. The project has only been tested on Go 1.12.

1. Copy config.toml.sample as config.toml and add your config.
2. make deps (to install Go dependencies for the backend and the JS dependencies for the frontend).
3. make build to build the listmonk binary. Once the binary is built, run ./listmonk --install to run the DB setup.

listmonk uses PostgreSQL as its data store and has only been tested with PostgreSQL 10.

mailhog is an excellent standalone mock SMTP server (with a UI) for testing and dev.

Running the dev environment

1. Run make run to start the listmonk Go server.
2. Run make run-frontend to start the React frontend (in dev mode using yarn).
3. Then visit http://localhost:9001 after setting up a dev proxy (see below).

Configuring with environment variables

Config keys in config.toml can also be provided to listmonk as environment variables prefixed by LISTMONK_ and periods are replaced by __ (double underscore). Example:

LISTMONK_db__host = "localhost"
LISTMONK_db__password = "xxxx"

Dev proxy

Setup an Nginx proxy endpoint

In the dev mode, although the frontend and backend are running as two independent servers, the requests should go via the same endpoint for the app to work. In production, this is not the case as the frontend is bundled into the server.

Here's a sample Nginx config that achieves this. Once this is up and running, visit http://localhost:9001 to access the frontend running in development mode where Javascript updates are pushed live.

# listmonk
server {
    listen 9001;

    # Proxy all /api/* requests to the Go backend.
    location /api {
        proxy_pass http://localhost:9000;
    }

    # Proxy everything else to the React frontend (yarn server).
    location / {
        proxy_pass http://localhost:3000;
    }
}

Production build

Run make dist (this will build the Go binary, build the Javascript frontend, and embed the static assets into the binary).