Skip to main content
This guide will help you set up a local development environment for contributing to listmonk.

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Go 1.24.1 or higher
  • Node.js 16+ and Yarn 1.22+
  • PostgreSQL 12+
  • Make (for build automation)
  • Git
The backend is written in Go and the frontend uses Vue.js with Buefy for the UI components.

​
Clone the Repository

1

Clone the repository

git clone https://github.com/knadh/listmonk.git
cd listmonk
2

Verify the directory structure

The repository contains:
  • cmd/ - Go application entry point
  • internal/ - Internal Go packages (core, manager, auth, etc.)
  • frontend/ - Vue.js admin interface
  • i18n/ - Internationalization files
  • static/ - Static assets and email templates
  • queries/ - SQL queries

​
Backend Setup

1

Install Go dependencies

Go modules are used for dependency management. Dependencies will be automatically downloaded when building:
go mod download
2

Build the backend

Build the listmonk binary:
make build
This creates the listmonk binary in the current directory.
3

Generate config file

./listmonk --new-config
Edit the generated config.toml file with your database credentials and settings.

​
Frontend Setup

1

Install frontend dependencies

Navigate to the frontend directory and install dependencies:
cd frontend
yarn install
cd ..
2

Build the email builder

The email builder is a separate component:
make build-email-builder
3

Build the frontend

make build-frontend
This compiles the Vue.js application and outputs to frontend/dist.
The frontend uses Vite as the build tool and ESLint for code linting. The linter runs automatically before builds.

​
Database Setup

1

Create PostgreSQL database

createdb listmonk
2

Run database installation

./listmonk --install
This sets up the database schema and creates the necessary tables.
Use --upgrade to upgrade an existing database. Upgrades are idempotent and can be run multiple times safely.
3

Create admin user

Follow the prompts to create your first admin user during installation.

​
Running in Development Mode

​
Backend Development

Run the backend in development mode with live frontend assets: 
make run
This starts the server and loads frontend assets from frontend/dist directory. 
make run

​
Frontend Development

For active frontend development with hot reload:
1

Start the frontend dev server

make run-frontend
This starts Vite dev server with hot module replacement (HMR).
2

Access the application

  • Frontend dev server: http://localhost:3000
  • Backend API: http://localhost:9000
When running the frontend dev server, configure it to proxy API requests to the backend server at http://localhost:9000.

​
Building for Production

​
Complete Build with Embedded Assets

Build everything and embed all assets into a single binary: 
make dist
This:
  1. Installs stuffbin (asset embedding tool)
  2. Builds the backend binary
  3. Builds the frontend
  4. Embeds all static assets, templates, and frontend into the binary

​
Individual Build Targets

make build

​
Project Structure

listmonk/
├── cmd/                    # Main application entry point
│   ├── main.go
│   ├── init.go
│   ├── handlers.go
│   └── ...
├── internal/               # Internal packages
│   ├── core/              # Core business logic
│   ├── manager/           # Campaign manager
│   ├── messenger/         # Message delivery (SMTP, etc.)
│   ├── auth/              # Authentication
│   ├── bounce/            # Bounce handling
│   ├── i18n/              # Internationalization
│   └── media/             # Media management
├── frontend/               # Vue.js admin interface
│   ├── src/
│   ├── public/
│   └── package.json
├── i18n/                   # Language files (JSON)
├── static/                 # Static assets
│   ├── email-templates/   # Email templates
│   └── public/            # Public assets
├── queries/                # SQL queries
├── schema.sql             # Database schema
├── config.toml.sample     # Sample configuration
└── Makefile               # Build automation

​
Testing

Run Go tests: 
make test
This executes all Go unit tests across the project.
For frontend testing, Cypress is configured. Check frontend/package.json for available test scripts.

​
Docker Development Environment

​
Using Docker Compose for Development

1

Build development Docker images

make build-dev-docker
2

Start the development environment

make dev-docker
This starts PostgreSQL, backend, and frontend containers.
3

Initialize the database

make init-dev-docker
4

Stop and clean up

make rm-dev-docker
This removes all containers and volumes.

​
Frontend Development Notes

​
Global Vue Plugins

In frontend/main.js, the following are attached globally:
  • Buefy - UI component framework
  • vue-i18n - Internationalization
  • $api - API calls from api/index.js
  • $utils - Utility functions from util.js
These are accessible in components as this.$api and this.$utils.

​
State Management

The project uses Vuex for global state management. API responses are stored centrally as “models” defined in constants.js. Check store/index.js for state definitions.

​
Icon Set

listmonk uses a custom subset of Material Design Icons via Fontello. The icon configuration is in frontend/fontello/config.json.
JSON field names in API responses are automatically camel-cased in the frontend. When sending data to the backend, manually convert to snake_case.

​
Development Workflow

  1. Make changes to backend (Go) or frontend (Vue) code
  2. Test locally using make run and make run-frontend
  3. Run tests with make test
  4. Build with make dist to verify production build
  5. Commit changes following the contribution guidelines

​
Troubleshooting

​
Build Issues

  • Ensure all prerequisites are installed and up to date
  • Clear build artifacts: rm -rf listmonk frontend/dist
  • Reinstall dependencies: go mod download && cd frontend && yarn install

​
Database Connection Issues

  • Verify PostgreSQL is running: pg_isready
  • Check config.toml database credentials
  • Ensure the database exists: psql -l | grep listmonk

​
Frontend Dev Server Issues

  • Clear node modules: cd frontend && rm -rf node_modules && yarn install
  • Check for port conflicts (default: 3000)
  • Verify backend is running on port 9000

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us