Installation

Option 1: Docker (Recommended)

Basic (no config)

docker run \
  -p 6667:6667 -p 6697:6697 -p 8080:8080 -p 8443:8443 \
  faelgabriel/elixircd

With custom config

docker run \
  -p 6667:6667 -p 6697:6697 -p 8080:8080 -p 8443:8443 \
  -v ./elixircd.exs:/app/config/elixircd.exs \
  -v ./motd.txt:/app/config/motd.txt \
  faelgabriel/elixircd

With SSL certificates

docker run \
  -p 6667:6667 -p 6697:6697 -p 8080:8080 -p 8443:8443 \
  -v ./elixircd.exs:/app/config/elixircd.exs \
  -v ./cert/:/app/data/cert/ \
  faelgabriel/elixircd

Docker Remote Commands

# Open an interactive Elixir shell connected to the running server
docker exec -it <container_name> ./bin/elixircd remote

# Gracefully stop the server
docker exec -it <container_name> ./bin/elixircd stop

---

Option 2: Building from Source

Requirements

• Elixir 1.19 or newer
• Erlang/OTP (compatible with your Elixir version)
• Git

We recommend using asdf to manage Elixir and Erlang versions.

1. Install asdf plugins

   asdf plugin-add erlang
   asdf plugin-add elixir

2. Clone the repository

   git clone https://github.com/faelgabriel/elixircd.git
   cd elixircd

3. Install the correct versions

   The .tool-versions file specifies the required Erlang and Elixir versions:

   asdf install

4. Install dependencies

   mix deps.get

5. Build a production release

   APP_VERSION=1.0.0 MIX_ENV=prod mix release

6. Start the server

   _build/prod/rel/elixircd/bin/elixircd start

Development Mode

For development and debugging, start in interactive mode:

iex -S mix

This opens an IEx shell with the server running, allowing live interaction.

Running Tests

mix test --cover

Code Quality Checks

mix quality

This runs compilation warnings, formatting, linting (Credo), security analysis (Sobelow), dependency audits, documentation checks, Dialyzer static analysis, and test coverage.

---

Configuration Files

After installation, the server looks for config files in these locations:

File	Location	Purpose
elixircd.exs	config/elixircd.exs (source) or /app/config/elixircd.exs (Docker)	Main server configuration
motd.txt	config/motd.txt or /app/config/motd.txt	Message of the Day
SSL certificates	data/cert/ or /app/data/cert/	TLS certificate files

Tip

In the Docker image, the config files are in /app/config/. Mount your custom files at these paths to override the defaults.

Default Ports

Port	Protocol	Purpose
6667	TCP	IRC plaintext
6697	TLS	IRC with SSL/TLS
8080	HTTP	WebSocket (IRC over WS)
8443	HTTPS	WebSocket with SSL/TLS

Note

By default, ports 6697 and 8443 use auto-generated self-signed certificates. For production, replace them with real certificates. See the SSL/TLS setup guide.

Building the Docker Image Locally

docker build -t elixircd .
docker run -p 6667:6667 -p 6697:6697 -p 8080:8080 -p 8443:8443 elixircd