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

```yaml
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` :

```docker
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`:

```yaml
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:

```env
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](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

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

- create an account and a project on [redirection.io](/content/site-root.html) and retrieve your `project key` in [redirection.io's manager](/content/manager/index.html) (click on the "Setup on your website" > "Setup on your infrastructure" button).
- copy the [`.env.dist`](https://github.com/redirectionio/docker-example/blob/master/.env.dist) configuration file to `.env` and paste the project key in this file:

```ini
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:

```sh
cd agent-as-reverse-proxy
```

- build the infrastructure:

```sh
docker-compose build
```

- run it:

```sh
docker-compose up -d
```

### Kubernetes example

For [Google Kubernetes Engine](https://cloud.google.com/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/](https://github.com/redirectionio/kubernetes-example/)

Basically, it uses images built using the above docker example, [for the redirectionio-agent](https://github.com/redirectionio/kubernetes-example/blob/master/agent-deployment.yaml) and for [nginx with the redirection.io module enabled](https://github.com/redirectionio/kubernetes-example/blob/master/proxy-deployment.yaml).

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](/content/contact/index.html)