Skip to main content
This guide walks you through setting up a complete development environment for Memos, including both backend (Go) and frontend (React) components.

​
Prerequisites

Backend Requirements

  • Go 1.25.7 or higher
  • Protocol Buffers compiler (buf)
  • golangci-lint for code linting

Frontend Requirements

  • Node.js 22 or higher
  • pnpm 10 or higher
  • TypeScript knowledge

​
Backend Setup

1

Install Go

Download and install Go 1.25.7 or higher from go.dev.Verify your installation:
go version
# Should output: go version go1.25.7 or higher
2

Clone the repository

git clone https://github.com/usememos/memos.git
cd memos
3

Install dependencies

Download Go dependencies:
go mod download
Verify dependencies are tidy:
go mod tidy
4

Install development tools

Install golangci-lint for code quality:
# 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

# Windows (via scoop)
scoop install golangci-lint
Install buf for Protocol Buffer generation:
# macOS
brew install bufbuild/buf/buf

# Linux/Windows
go install github.com/bufbuild/buf/cmd/buf@latest
Install goimports for formatting:
go install golang.org/x/tools/cmd/goimports@latest
5

Start the backend server

Run the development server:
go run ./cmd/memos --port 8081
The backend API will be available at http://localhost:8081.
Use --port flag to run on a different port if 8081 is already in use.

​
Frontend Setup

1

Install Node.js and pnpm

Install Node.js 22 or higher from nodejs.org.Install pnpm globally:
npm install -g pnpm@10
Verify installations:
node --version  # Should be v22 or higher
pnpm --version  # Should be 10.x
2

Install frontend dependencies

Navigate to the web directory:
cd web
Install dependencies:
pnpm install
3

Start the development server

Start Vite dev server with hot reload:
pnpm dev
The frontend will be available at http://localhost:5173.
The dev server automatically proxies API requests to http://localhost:8081. Make sure the backend is running first.

​
Database Setup

Memos supports three database backends: SQLite (default), MySQL, and PostgreSQL.

​
SQLite (Default)

No additional setup required. SQLite runs in-memory or uses a local file: 
go run ./cmd/memos --port 8081
Data is stored in ~/.memos/memos_prod.db.

​
MySQL

1

Start MySQL

Using Docker:
docker run -d \
  --name memos-mysql \
  -e MYSQL_ROOT_PASSWORD=password \
  -e MYSQL_DATABASE=memos \
  -p 3306:3306 \
  mysql:8
2

Run with MySQL

DRIVER=mysql DSN="root:password@tcp(localhost:3306)/memos" go run ./cmd/memos

​
PostgreSQL

1

Start PostgreSQL

Using Docker:
docker run -d \
  --name memos-postgres \
  -e POSTGRES_PASSWORD=password \
  -e POSTGRES_DB=memos \
  -p 5432:5432 \
  postgres:16
2

Run with PostgreSQL

DRIVER=postgres DSN="postgres://postgres:password@localhost:5432/memos?sslmode=disable" go run ./cmd/memos

​
Protocol Buffers Setup

Memos uses Protocol Buffers for API definitions and type-safe communication between frontend and backend.
1

Install buf

Already covered in backend setup. Verify:
buf --version
2

Generate code from .proto files

Navigate to the proto directory:
cd proto
Generate Go and TypeScript code:
buf generate
This creates:
  • Go code in proto/gen/api/v1/
  • TypeScript code in web/src/types/proto/api/v1/
3

Lint proto files

buf lint

​
Verify Your Setup

Run these commands to ensure everything is working: 
# Backend tests
go test ./...

# Backend linting
golangci-lint run

# Frontend type checking
cd web && pnpm lint

# Frontend build
pnpm build

​
Environment Variables

​
Backend Variables

VariableDefaultDescription
MEMOS_PORT8081HTTP server port
MEMOS_ADDR“Bind address (empty = all interfaces)
MEMOS_DATA~/.memosData directory for SQLite and assets
MEMOS_DRIVERsqliteDatabase driver: sqlite, mysql, postgres
MEMOS_DSN“Database connection string
MEMOS_DEMOfalseEnable demo mode with sample data
MEMOS_INSTANCE_URL“Instance base URL for webhooks

​
Frontend Variables

VariableDefaultDescription
DEV_PROXY_SERVERhttp://localhost:8081Backend API proxy target
Create a .env file in the root directory to set environment variables during development.

​
IDE Setup

​
Visual Studio Code

Recommended extensions:
  • Go (golang.go) - Go language support
  • Protocol Buffers (zxh404.vscode-proto3) - Proto syntax highlighting
  • Biome (biomejs.biome) - Frontend linting and formatting
  • Tailwind CSS IntelliSense - Tailwind class completions

​
GoLand / WebStorm

JetBrains IDEs have built-in support for Go, TypeScript, and Protocol Buffers. Configure:
  1. Go to Settings → Languages & Frameworks → Go
  2. Set Go SDK to 1.25.7
  3. Enable Go Modules integration

​
Troubleshooting

Change the backend port:
go run ./cmd/memos --port 8082
Update the frontend proxy target in web/vite.config.mts or set:
DEV_PROXY_SERVER=http://localhost:8082 pnpm dev
Clear pnpm cache and retry:
pnpm store prune
pnpm install --force
Ensure buf is installed and updated:
buf --version
# Update if needed
go install github.com/bufbuild/buf/cmd/buf@latest
Clean and re-download modules:
go clean -modcache
go mod download
go mod tidy

​
Next Steps

Building

Learn how to build production binaries and Docker images

Testing

Write and run tests for your changes

Contributing

Submit your first pull request

Build docs developers (and LLMs) love

Get started for freeTalk to us