Creating your own Gemini capsule

I would like to share with you the process of creating your own capsule for the Gemini protocol. I will use Agate, a Gemini server written in Rust and recommended by the community. On the other hand, we will rely on Docker to make the installation and configuration easier. Therefore, you will need to have Docker installed on your system before continuing. Shall we start?

We will start by creating a file called Dockerfile. We will use it to compile Agate and build a Docker image.

FROM rust:alpine AS builder
RUN wget -O source.tar.gz $(wget -qO- https://api.github.com/repos/mbrubeck/agate/releases/latest | sed -nE 's/^.*"tarball_url"\s*:\s*"([^"]+)".*$/\1/p') && tar xzf source.tar.gz && \
    mv mbrubeck-agate-* /agate

WORKDIR /agate
RUN apk --no-cache add libc-dev && \
    cargo install --path .

FROM alpine:latest
COPY --from=builder /usr/local/cargo/bin/agate /usr/bin/agate
WORKDIR /app

It is a multi-stage Docker image.

1. Downloads the Rust image with Alpine.
2. Fetches the Agate source code.
3. Compiles Agate with cargo, the Rust package manager.
4. Creates an Alpine image with Agate installed and sets /app as the working directory. This last detail is important: Agate stores the TLS certificates in .certificates, relative to the working directory, and this way we will be able to persist them with a volume.

With the image defined, we will create a file called compose.yml to configure the Agate service.

services:

  agate:
    build: .
    restart: "always"
    ports:
      - "1965:1965"
    command: >
      agate --content /gmi/
      --hostname your-domain.com
      --addr [::]:1965
      --addr 0.0.0.0:1965
      --lang en-US
      --skip-port-check
    volumes:
      - ./gmi:/gmi
      - ./gmi/.certificates:/app/.certificates

In this file, we define a service called agate that uses the image we created earlier.

1. restart: "always": Restarts the service if it stops.
2. ports: Maps port 1965 of the container to port 1965 of the host. It is the default port of the Gemini protocol.
3. command: Configures Agate with the following parameters:
4. --content /gmi/: Indicates the folder where the capsule content is located.
5. --hostname your-domain.com: The domain we will use to access the server.
6. --addr [::]:1965 and --addr 0.0.0.0:1965: Listens on all network interfaces.
7. --lang en-US: Sets the language of the server.
8. --skip-port-check: Skips the port check.
9. volumes: Maps the local folders gmi and gmi/.certificates to the container. The /app/.certificates folder is where Agate stores the TLS certificates. Persisting them is important: Gemini uses the TOFU principle (Trust On First Use), and if they are regenerated every time the container is recreated, your visitors will see a certificate change warning.

After defining the Docker service, we move on to the next step.

We will need some minimal content to show our visitors, and at the same time to be able to check that the server is working correctly.

To do this, create the gmi folder, at the same level as the compose.yml file and the Dockerfile, and inside the new folder create a file called index.gmi with the following content:

# Welcome to my Gemini server

This is a Gemini server I have created to share content in a simple and secure way.

Everything is ready to bring up the server. Open a terminal in the folder where you created the files and run the following command:

docker compose up -d

I warn you in advance that the first time it will take a while, since it has to download the images and compile Agate. Remember that it is written in Rust.

Once it finishes, open your Gemini browser and type gemini://your-domain.com in the address bar.

If you are working locally, or you do not have a domain, you can add the following line to your /etc/hosts file to simulate one:

127.0.0.1 your-domain.com

You must do this because the Gemini protocol uses TLS certificates by default, it will deny access if you do not enter through the domain you have configured.

If everything went well, you should see the content you created in the index.gmi file.

Congratulations! You have just created your Gemini capsule. 🎉

If you need to redirect the domain from another server, you can visit Reverse proxy for the Gemini protocol.

Keep reading about Gemini

• Introduction to the Gemini protocol
• Gemtext or Gemini syntax with its HTML equivalents
• Reverse proxy for the Gemini protocol