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

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:

# 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 script. This handles binary download, configuration file creation, and service registration:

/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:

• Detects OS (Linux or Darwin) and CPU architecture
• Downloads the appropriate release archive from GitHub
• Creates a default config.yaml based on 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:

# 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:

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:

# 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:

# If running directly

easegress-server &

# If using systemd

systemctl status easegress

Docker:

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 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}