Development Setup

Set up your local development environment for contributing to Meshery.

This guide will help you set up a local development environment for contributing to Meshery.

Prerequisites

Required Software

Go (for Server and CLI development)

Version: Go 1.21 or later

Installation:

# macOS
brew install go

# Linux (download from official site)
wget https://go.dev/dl/go1.21.0.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.21.0.linux-amd64.tar.gz
export PATH=$PATH:/usr/local/go/bin

Verify:

go version

Node.js (for UI development)

Version: Node.js 16, 17, 18, 19, or 20

Installation:

# macOS
brew install node@20

# Linux (using nvm)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20
nvm use 20

Verify:

node --version
npm --version

Docker (for containerized builds)

Installation:

# macOS
brew install --cask docker

# Linux (Ubuntu/Debian)
sudo apt-get update
sudo apt-get install docker.io
sudo systemctl start docker
sudo usermod -aG docker $USER

Verify:

docker --version
docker ps

Git (version control)

Installation:

# macOS
brew install git

# Linux (Ubuntu/Debian)
sudo apt-get install git

Configure:

git config --global user.name "Your Name"
git config --global user.email "[e-mail]"

Verify:

git --version

Make (build automation)

Installation:

# macOS (included with Xcode Command Line Tools)
xcode-select --install

# Linux (Ubuntu/Debian)
sudo apt-get install build-essential

Verify:

make --version

Optional Tools

• PostgreSQL – For local database testing
• kubectl – For Kubernetes integration testing
• kind – For local Kubernetes cluster testing
• helm – For Helm chart development and testing

Cloning the Repository

Fork and Clone

1. Fork the repository on GitHub:

   • Visit github.com/meshery/meshery
   • Click the “Fork” button in the top right

2. Clone your fork:

git clone https://github.com/YOUR_USERNAME/meshery.git
cd meshery

3. Add upstream remote:

git remote add upstream https://github.com/meshery/meshery.git
git fetch upstream

4. Create a feature branch:

git checkout -b feature/your-feature-name

Server Development Setup

Install Go Dependencies

cd server/cmd
go mod tidy
cd ../..

Install golangci-lint

golangci-lint is used for linting Go code.

# macOS
brew install golangci-lint

# Linux
curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin

Run Meshery Server Locally

Basic server (port 9081):

make server

The server will be available at http://localhost:9081.

Run with local provider:

make server-local

Run without Kubernetes components:

make server-skip-compgen

Run without operator deployment:

make server-without-operator

Build Server Binary

make build-server

This creates a main binary in the project root.

Run the binary:

make server-binary

Lint Go Code

make golangci

Generate Error Codes

Meshery uses MeshKit’s error utility for error handling:

make error

UI Development Setup

Install UI Dependencies

make ui-setup

This installs dependencies for both ui/ and provider-ui/ directories.

Run Meshery UI Locally

Development server (port 3000):

make ui

The UI will be available at http://localhost:3000.

The UI expects the Meshery Server to be running at http://localhost:9081. Run make server in a separate terminal.

Run Provider UI

make ui-provider

Lint UI Code

make ui-lint

Build UI for Production

Build all UIs:

make ui-build

Build only Meshery UI:

make ui-meshery-build

Build only Provider UI:

make ui-provider-build

CLI Development Setup

Build mesheryctl

cd mesheryctl
make

This creates the mesheryctl binary in mesheryctl/ directory.

Run mesheryctl

./mesheryctl/mesheryctl version

Run Unit Tests

cd mesheryctl
go test --short ./...

Run Integration Tests

cd mesheryctl
go test -run Integration ./...

Docker Development Setup

Build Meshery Container

make docker-build

This builds Meshery inside a multi-stage Docker container using BuildKit.

Build Playground Mode Container

make docker-playground-build

Run Meshery in Docker

With production Remote Provider:

make docker-cloud

With local Remote Provider:

make docker-local-cloud

Documentation Development Setup

Install Jekyll Dependencies

cd docs
bundle install

Run Documentation Site Locally

With live reload (port 4000):

make docs

The docs will be available at http://localhost:4000.

Without live reload:

make docs-serve

Build Documentation

make docs-build

Run Docs in Docker

make docs-docker

Environment Variables

Meshery Server accepts several environment variables for configuration:

Variable	Description	Default
PORT	Server port	9081
DEBUG	Enable debug logging	false
PROVIDER_BASE_URLS	Remote provider URLs	Production URLs
ADAPTER_URLS	Adapter service URLs	-
KEYS_PATH	Path to encryption keys	-
SKIP_COMP_GEN	Skip Kubernetes component generation	false
DISABLE_OPERATOR	Disable operator deployment	false
PLAYGROUND	Enable playground mode	false

Example:

export PORT=9081
export DEBUG=true
make server

Verifying Your Setup

Quick Verification

Run these commands to verify your setup:

# Check Go installation
go version

# Check Node.js installation
node --version

# Check Docker installation
docker --version

# Check Make installation
make --version

# Lint server code
make golangci

# Lint UI code
make ui-lint

Full Build Test

Test that you can build all components:

# Build server
make build-server

# Build UI
make ui-build

# Build CLI
cd mesheryctl && make && cd ..

# Build Docker container
make docker-build

Troubleshooting

Go version mismatch

If you see warnings about Go version:

# Check installed version
go version

# Update Go to 1.21 or later
brew upgrade go  # macOS

Node.js version issues

The Makefile automatically detects Node.js version and uses appropriate build scripts. Supported versions: 16, 17, 18, 19, 20.

# Check Node version
node --version

# Switch to Node 20 with nvm
nvm use 20

Docker permission denied

On Linux, you may need to add your user to the docker group:

sudo usermod -aG docker $USER
newgrp docker

Port already in use

If port 9081 or 3000 is already in use:

# Check what's using the port
lsof -i :9081
lsof -i :3000

# Kill the process or use a different port
export PORT=9082
make server

golangci-lint not found

Install golangci-lint:

# macOS
brew install golangci-lint

# Linux
curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin

# Verify
golangci-lint --version

Next Steps

Code Style Guide

Learn Meshery’s coding conventions

Server Development

Start contributing to the Go backend

UI Development

Start contributing to the React frontend

Testing Guide

Learn how to test your changes