# How to Install Easegress: Complete Guide for Binary, Source, and Docker

> Easily Install Easegress with our complete guide covering binary deployment via script, building from source for custom features, and running the official Docker image for containerized setups.

- Repository: [easegress-io/easegress](https://github.com/easegress-io/easegress)
- Tags: getting-started
- Published: 2026-03-01

---

**Install Easegress using the official install script for automated binary deployment, build from source with Go 1.20+ for custom features, or run the official Docker image for containerized environments.**

This guide covers every method to install Easegress from the `easegress-io/easegress` repository. Whether you need a quick binary setup for development, a production systemd service, or a containerized deployment, the following sections provide copy-paste commands and configuration details sourced directly from the official codebase.

## Installing the Pre-built Binary (Quick Start)

The fastest way to install Easegress uses the pre-compiled release binaries hosted on GitHub.

### Manual Binary Download

Download and extract the archive for your platform, then add the binaries to your `PATH`:

```bash

# Download the latest release (adjust version and architecture as needed)

curl -L -o easegress.tar.gz \
  https://github.com/megaease/easegress/releases/download/v2.6.1/easegress-v2.6.1-linux-amd64.tar.gz

# Extract the archive

tar -zxf easegress.tar.gz

# Add to PATH and verify

export PATH="$PATH:$(pwd)/easegress/bin"
easegress-server --version

```

### Using the Official Install Script

For automated installation and systemd setup, use the [`scripts/install.sh`](https://github.com/easegress-io/easegress/blob/main/scripts/install.sh) script. This handles binary download, configuration file creation, and service registration:

```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/megaease/easegress/main/scripts/install.sh)"

```

The script performs the following actions defined in [`scripts/install.sh`](https://github.com/easegress-io/easegress/blob/main/scripts/install.sh):

- Detects OS (`Linux` or `Darwin`) and CPU architecture
- Downloads the appropriate release archive from GitHub
- Creates a default [`config.yaml`](https://github.com/easegress-io/easegress/blob/main/config.yaml) based on [`scripts/config.yaml`](https://github.com/easegress-io/easegress/blob/main/scripts/config.yaml)
- On Linux systems, downloads the systemd unit file from `scripts/easegress.service`, updates the binary path, and enables the service via `systemctl`

## Building Easegress from Source

Building from source requires Go 1.20 or later and provides access to the latest features and custom build tags.

### Prerequisites

- **Go**: Version 1.20 or higher
- **Git**: For cloning the repository
- **Make**: For running build targets

### Build Steps

Clone the repository and run the Makefile:

```bash

# Clone the source

git clone https://github.com/megaease/easegress.git
cd easegress

# Build binaries (creates ./bin/easegress-server, ./bin/egctl, etc.)

make

# Add to PATH

export PATH="$PATH:$(pwd)/bin"

# Verify build

easegress-server --version

```

### Enabling WebAssembly Support

To build with WebAssembly (Wasm) runtime support, use the `wasm` build target:

```bash
make wasm

```

This compiles the Wasm host and registers the Wasm runtime, enabling Easegress to execute WebAssembly modules as described in the build documentation.

## Running Easegress with Docker

For containerized environments, use the official Docker image:

```bash

# Pull the latest image

docker pull megaease/easegress:latest

# Run the container

docker run -d --name easegress \
  -p 2379:2379 \
  -p 2380:2380 \
  -p 2381:2381 \
  -p 10080:10080 \
  megaease/easegress:latest

```

This exposes the default Easegress ports: `2379` (client requests), `2380` (peer communication), `2381` (metrics), and `10080` (HTTP traffic).

## Validating Your Installation

After installation, verify the server starts correctly:

**Binary or Systemd:**

```bash

# If running directly

easegress-server &

# If using systemd

systemctl status easegress

```

**Docker:**

```bash
docker logs easegress

```

Look for startup logs indicating successful initialization, such as:

```

2023-09-06T15:12:49.256+08:00   INFO    cluster/config.go:110   config: advertise-client-urls: ...

```

## Summary

- **Pre-built binary**: Fastest method using `curl` to download releases or the [`scripts/install.sh`](https://github.com/easegress-io/easegress/blob/main/scripts/install.sh) script for automated setup.
- **Build from source**: Requires Go 1.20+; use `make` for standard builds or `make wasm` for WebAssembly support.
- **Systemd service**: The install script registers `easegress` as a systemd unit on Linux systems, creating the service file from `scripts/easegress.service`.
- **Docker**: Use the `megaease/easegress` image for containerized deployments exposing ports 2379-2381 and 10080.

## Frequently Asked Questions

### What is the fastest way to install Easegress?

The fastest way is using the official install script at [`scripts/install.sh`](https://github.com/easegress-io/easegress/blob/main/scripts/install.sh), which automates the binary download, extracts the archive, creates a default configuration file, and optionally registers a systemd service. Alternatively, manually download the pre-built binary from the GitHub releases page and extract it to your preferred directory.

### How do I install Easegress as a systemd service?

Run the official install script on a Linux system with systemd. The script downloads the unit file from `scripts/easegress.service`, updates the binary path to match your installation directory, and executes `systemctl enable easegress` and `systemctl start easegress`. You can verify the service status using `systemctl status easegress`.

### Can I install Easegress without root privileges?

Yes, you can install Easegress without root by using the pre-built binary method or building from source. Download the release archive to a user-owned directory (such as `$HOME/easegress`), extract it, and add the `bin` directory to your user PATH. The install script also supports non-root installation if you skip the systemd registration step.

### What Go version is required to build Easegress from source?

Easegress requires **Go 1.20 or later** to build from source. Clone the repository from `github.com/megaease/easegress`, ensure your Go environment is properly configured, and run `make` in the repository root to compile the `easegress-server` and `egctl` binaries. For WebAssembly support, use `make wasm` instead.