Sign inSign up

xuqwinner/frp

By xuqwinner

•Updated about 2 months ago

Docker image for FRP (frps / frpc)

Image
Networking
0

4.4K

xuqwinner/frp repository overview

⁠FRP Docker Image

A unified Docker image for frp⁠ (Fast Reverse Proxy) that supports both frps (server) and frpc (client) modes via a single environment variable.

⁠Features

  • Single image, dual mode — switch between frps and frpc with FRP_ROLE env
  • Multi-platform — linux/amd64 and linux/arm64
  • Version flexible — build with any release version or auto-resolve latest
  • Bundled defaults — ships with official frps.toml and frpc.toml from the release package
  • Health check — built-in Docker health check (dashboard endpoint + process fallback)
  • Minimal footprint — Alpine-based, ~20MB compressed

⁠Quick Start

⁠Pull from Docker Hub
docker pull xuqwinner/frp:latest
# or a specific version
docker pull xuqwinner/frp:0.68.1
⁠Run as Server (frps)
docker run -d \
  --name frps \
  --network host \
  -e FRP_ROLE=frps \
  -v ./frps.toml:/etc/frp/frps.toml:ro \
  xuqwinner/frp:latest
⁠Run as Client (frpc)
docker run -d \
  --name frpc \
  --network host \
  -e FRP_ROLE=frpc \
  -v ./frpc.toml:/etc/frp/frpc.toml:ro \
  xuqwinner/frp:latest
⁠Run with Bundled Default Config (no mount needed)
docker run -d --name frps --network host -e FRP_ROLE=frps xuqwinner/frp:latest

⁠Docker Compose

# ============================================================
# FRP Docker Compose
#
# Usage:
#   1. Edit frps.toml / frpc.toml to match your setup
#   2. Run: docker compose up -d
#
# You can run frps and frpc on the SAME or DIFFERENT hosts.
# Comment out whichever service you don't need.
# ============================================================

x-logging: &logging
  logging:
    driver: json-file
    options:
      max-size: 10m
      max-file: 3

services:
  # ---- FRP Server (frps) ----
  # Deploy on your public-facing server
  frps:
    image: xuqwinner/frp:latest
    container_name: frps
    restart: unless-stopped
    network_mode: host
    environment:
      - FRP_ROLE=frps
    volumes:
      - ./frps.toml:/etc/frp/frps.toml:ro
    <<: *logging

  # ---- FRP Client (frpc) ----
  # Deploy on your internal/NAT server
  frpc:
    image: xuqwinner/frp:latest
    container_name: frpc
    restart: unless-stopped
    network_mode: host
    environment:
      - FRP_ROLE=frpc
    volumes:
      - ./frpc.toml:/etc/frp/frpc.toml:ro
    <<: *logging

⁠Environment Variables

VariableDefaultDescription
FRP_ROLEfrpsRun mode: frps (server) or frpc (client)
FRP_CONFIG/etc/frp/${FRP_ROLE}.tomlPath to config file inside container

⁠Configuration

The image ships with the official default config files from the frp release package. To customize:

Option 1: Mount your own config file

docker run -d \
  -e FRP_ROLE=frps \
  -v /path/to/your/frps.toml:/etc/frp/frps.toml:ro \
  xuqwinner/frp:latest

Option 2: Export the bundled default config, then modify

docker run --rm --entrypoint cat xuqwinner/frp:latest /etc/frp/frps.toml > frps.toml
docker run --rm --entrypoint cat xuqwinner/frp:latest /etc/frp/frpc.toml > frpc.toml

⁠Health Check

The built-in health check works in two tiers:

  1. Dashboard endpoint — if webServer is enabled in your config, it probes /healthz (frps on port 7500, frpc on port 7400)
  2. Process fallback — if the dashboard is not enabled, it checks whether the frp process is alive via pidof

To enable dashboard-based health checks, add this to your config:

# frps.toml
webServer.addr = "0.0.0.0"
webServer.port = 7500

# frpc.toml
webServer.addr = "0.0.0.0"
webServer.port = 7400

Tag summary

Content type

Image

Digest

sha256:0a5e200a5…

Size

17.1 MB

Last updated

about 2 months ago

docker pull xuqwinner/frp