Building a Server

RoadRunner uses Endure to manage dependencies, this allows you to tweak and extend application functionality for each separate project.

Compatibility with the plugins:

  1. ⚠️ Do not use the plugin's master branch.
  2. ⚠️ Use tags with the same major version (e.g logger v3.0.3 + amqp v3.0.5, but not logger v4.0.0 + amqp v3.0.5)
  3. ⚠️ Currently supported plugins version is: v3.x.x
  4. ⚠️ Currently supported RR version is: v2.12.x

GitHub plugin template

How to write a plugin

  • Writing a plugin

  • Velox configuration

configuration

Install Golang

To build an application server you need Golang 1.20+ or Docker to be installed.

Installation:

  • Docker:
dockerfile
# https://docs.docker.com/buildx/working-with-buildx/
# TARGETPLATFORM if not empty OR linux/amd64 by default
FROM --platform=${TARGETPLATFORM:-linux/amd64} ghcr.io/roadrunner-server/velox:latest as velox

# app version and build date must be passed during image building (version without any prefix).
# e.g.: `docker build --build-arg "APP_VERSION=1.2.3" --build-arg "BUILD_TIME=$(date +%FT%T%z)" .`
ARG APP_VERSION="undefined"
ARG BUILD_TIME="undefined"

# copy your configuration into the docker
COPY velox.toml .

# we don't need CGO
ENV CGO_ENABLED=0

# RUN build
RUN vx build -c velox.toml -o /usr/bin/

FROM --platform=${TARGETPLATFORM:-linux/amd64} php:8.1-cli

# copy required files from builder image
COPY --from=velox /usr/bin/rr /usr/bin/rr

# use roadrunner binary as image entrypoint
CMD ["/usr/bin/rr"]
  • go install command:
shell
go install github.com/roadrunner-server/velox/cmd/vx@latest
  • Or download velox binary from the releases page and unpack to your PATH.

Configuration:

toml
# filename - `plugins.toml`

[velox]
build_args = ['-trimpath', '-ldflags', '-s -X github.com/roadrunner-server/roadrunner/v2/internal/meta.version=${VERSION} -X github.com/roadrunner-server/roadrunner/v2/internal/meta.buildTime=${TIME}']

[roadrunner]
ref = "v2.12.1"

[github]
    [github.token]
    token = "${RT_TOKEN}"

    [github.plugins]
    # LOGS
    appLogger = { ref = "v3.2.0", owner = "roadrunner-server", repository = "app-logger" }
    logger = { ref = "v3.2.0", owner = "roadrunner-server", repository = "logger" }

    # CENTRIFUGE BROADCASTING PLATFORM
    centrifuge = { ref = "v3.2.0", owner = "roadrunner-server", repository = "centrifuge" }

    # WORKFLOWS ENGINE
    temporal = { ref = "v3.0.0", owner = "temporalio", repository = "roadrunner-temporal" }

    # METRICS
    metrics = { ref = "v3.3.0", owner = "roadrunner-server", repository = "metrics" }

    # HTTP + MIDDLEWARE
    http = { ref = "v3.2.0", owner = "roadrunner-server", repository = "http" }
    gzip = { ref = "v3.2.0", owner = "roadrunner-server", repository = "gzip" }
    prometheus = { ref = "v3.2.0", owner = "roadrunner-server", repository = "prometheus" }
    headers = { ref = "v3.2.0", owner = "roadrunner-server", repository = "headers" }
    static = { ref = "v3.2.0", owner = "roadrunner-server", repository = "static" }
    otel = { ref = "v3.2.0", owner = "roadrunner-server", repository = "otel" }
    cache = { ref = "master", owner = "darkweak", repository = "souin", folder = "/plugins/roadrunner" }

    # RELOAD (for the DEV)
    reload = { ref = "v3.2.0", owner = "roadrunner-server", repository = "reload" }

    # SERVER
    server = { ref = "v3.2.0", owner = "roadrunner-server", repository = "server" }

    # SERVICE aka lightweit systemd
    service = { ref = "v3.2.0", owner = "roadrunner-server", repository = "service" }

    # JOBS
    jobs = { ref = "v3.2.0", owner = "roadrunner-server", repository = "jobs" }
    amqp = { ref = "v3.3.0", owner = "roadrunner-server", repository = "amqp" }
    sqs = { ref = "v3.3.0", owner = "roadrunner-server", repository = "sqs" }
    beanstalk = { ref = "v3.2.0", owner = "roadrunner-server", repository = "beanstalk" }
    nats = { ref = "v3.2.0", owner = "roadrunner-server", repository = "nats" }
    kafka = { ref = "v3.0.4", owner = "roadrunner-server", repository = "kafka" }

    # KV
    kv = { ref = "v3.2.0", owner = "roadrunner-server", repository = "kv" }
    boltdb = { ref = "v3.2.0", owner = "roadrunner-server", repository = "boltdb" }
    memory = { ref = "v3.3.0", owner = "roadrunner-server", repository = "memory" }
    redis = { ref = "v3.2.0", owner = "roadrunner-server", repository = "redis" }
    memcached = { ref = "v3.2.0", owner = "roadrunner-server", repository = "memcached" }

    # FILESERVER (static files)
    fileserver = { ref = "v3.2.0", owner = "roadrunner-server", repository = "fileserver" }

    # gRPC plugin
    grpc = { ref = "v3.2.0", owner = "roadrunner-server", repository = "grpc" }

    # HEALTHCHECKS + READINESS CHECKS
    status = { ref = "v3.2.0", owner = "roadrunner-server", repository = "status" }

    # TCP for the RAW TCP PAYLOADS
    tcp = { ref = "v3.2.0", owner = "roadrunner-server", repository = "tcp" }

[gitlab]
    [gitlab.token]
    # api, read-api, read-repo
    token = "${GL_TOKEN}"

    [gitlab.endpoint]
    endpoint = "https://gitlab.com"

    [gitlab.plugins]
    # ref -> master, commit or tag
    test_plugin_1 = { ref = "main", owner = "rustatian", repository = "36405203" }
    test_plugin_2 = { ref = "main", owner = "rustatian", repository = "36405235" }

[log]
level = "debug"
mode = "development"

Usage:

shell
vx build -c plugins.toml -o ~/Downloads

Where:

  • -c - path to the configuration
  • -o - path where to put the RR binary

Environment variables:

  • "${GL_TOKEN}" - GitLab token.
  • "${RT_TOKEN}" - GitHub token.
  • "${VERSION}" - RR version to write into the binary (will be shown with ./rr --version).
  • "${TIME}" - Build time (will be shown with ./rr --version).

Supported options for the plugins:

  • ref: tag, commit hash or branch name.
  • owner: repository owner (might be the user or organization).
  • repository: repository name.
  • folder: if the plugin is in some folder in your repository, you may specify it via this configuration option. For example: cache = { ref = "v1.6.18", owner = "darkweak", repository = "souin", folder="plugins/roadrunner" }.
  • replace: go.mod replace directive.

Known limitation

  • At the moment only GitHub and GitLab repositories are supported.
Edit this page