Using redirection.io with Docker - Developer documentation | Documentation

Using redirection.io with Docker

It is quite common to use Docker in development or production environments. redirection.io can be easily integrated in a Docker-based infrastructure, and this documentation page explains how to do it.

Using the redirection.io agent as a reverse proxy in Docker

Add a new redirectionio-agent service with docker-compose:

volumes:
    redirectionio-data: {}

services:
  application:
    # your application service

redirectionio-agent:
    build: services/redirectionio-agent
    ports:
      - "127.0.0.1:8443:443"
      - "127.0.0.1:8080:80"
    volumes:
      - redirectionio-data:/var/lib/redirectionio
    environment:
      - INSTANCE_NAME=${REDIRECTIONIO_INSTANCE_NAME}
      - REDIRECTIONIO_PROJECT_KEY=${REDIRECTIONIO_PROJECT_KEY}

Define the corresponding service in its Dockerfile, in services/redirectionio-agent/Dockerfile :

FROM alpine:3.23 as alpine

WORKDIR /tmp

RUN apk add --no-cache wget ca-certificates \
    && wget https://packages.redirection.io/dist/stable/3/any/redirectionio-agent-latest_any_amd64.tar.gz \
    && tar -xzvf redirectionio-agent-latest_any_amd64.tar.gz

FROM scratch

# Binary copied from tar
COPY --from=alpine /tmp/redirection-agent/redirectionio-agent /usr/local/bin/redirectionio-agent

# Configuration, can be replaced by your own
COPY etc /etc

# Root SSL Certificates, needed as we do HTTPS requests to our service
COPY --from=alpine /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/

# Cache storage for rules
VOLUME /var/lib/redirectionio

CMD ["/usr/local/bin/redirectionio-agent"]

Also, set the redirection.io configuration in services/redirectionio-agent/etc/redirectionio/agent.yml:

instance:
    name: "${INSTANCE_NAME}"

reverse_proxy:
    listen:
        - tcp://0.0.0.0:80
        - tls://0.0.0.0:443
    forward:
        address: application:80
    agent:
        project_key: "${REDIRECTIONIO_PROJECT_KEY}"
    certificate:
        file:
            key: "/etc/ssl/private/ssl-cert-snakeoil.key"
            certificates:
            - "/etc/ssl/certs/ssl-cert-snakeoil.pem"

This file uses two environment variables (REDIRECTIONIO_PROJECT_KEY and INSTANCE_NAME) that are passed by docker. Set the according values in a .env file:

REDIRECTIONIO_INSTANCE_NAME=docker dev env
REDIRECTIONIO_PROJECT_KEY=YOUR PROJECT KEY HERE

Ready-to-use docker example project

As this has been requested by several of our users, we have set up different examples to show how to integrate redirection.io in various Docker setups. This sample project can be found on our Github account: https://github.com/redirectionio/docker-example

We do not distribute docker images for the redirection.io agent, as we believe this would be counterproductive. The agent itself is a single static binary and, given the diversity on docker images construction methods, we think it is simpler to use these examples as inspiration for your own context.

Available Docker layouts

agent-as-reverse-proxy: the redirection.io agent, installed from our repository, is used as a reverse proxy. This is the most simple and recommended setup.
apache-module: a simple Apache setup, with redirection.io module installed from our apt repository
apache-module-custom: an Apache setup with the redirection.io module compiled from sources
nginx-module: a simple nginx setup, with redirection.io module installed from our apt repository
nginx-module-custom: a nginx setup with the redirection.io module compiled from sources

Usage

clone the repository

git clone https://github.com/redirectionio/docker-example.git
cd docker-example

create an account and a project on redirection.io and retrieve your project key in redirection.io's manager (click on the "Setup on your website" > "Setup on your infrastructure" button).
copy the .env.dist configuration file to .env and paste the project key in this file:

REDIRECTIONIO_PROJECT_KEY=PASTE HERE YOUR REDIRECTION.IO PROJECT KEY

choose one of the docker example layouts proposed in the project and navigate to the according directory. For example:

cd agent-as-reverse-proxy

build the infrastructure:

docker-compose build

run it:

docker-compose up -d

Kubernetes example

For Google Kubernetes Engine (GKE) users, we provide an example GKE project that may be helpful to get redirection.io work in your context: https://github.com/redirectionio/kubernetes-example/

Basically, it uses images built using the above docker example, for the redirectionio-agent and for nginx with the redirection.io module enabled.

Of course, you'll have to do some changes for your own context, but this might be helpful in case of troubles.

This page has been updated on Apr 15, 2026

Can't find your answer?

Contact our support