Gabriel Fontes

Servidor de Factorio declarativo com NixOS+Terraform no Magalu Cloud

Thu, 04 Sep 2025 00:00:00 +0000

This blog post was originally published on dev.to as a guide for Magalu Cloud (my employer) hackathon’s participants.

Uma dúvida comum que pessoas novas ao Terraform têm é: “depois de criar a VM, como eu rodo minha aplicação?”. Algumas soluções incluem cloud-init, Ansible, etc.

Nesse guia, eu quero mostrar uma das melhores (na minha opinião) soluções para isso: o NixOS. Mostrarei como usar Terraform + NixOS para provisionar um servidor já rodando uma aplicação de sua escolha, sem nenhum passo manual.

Factorio é um jogo de automação com uma qualidade absurda e uma gameplay extremamente polida. Se você valoriza seu sono, recomendo não jogar! Pro resto de nós, já viciados, a fábrica deve crescer!

Com isso em mente, esse guia irá, como exemplo divertido, focar em subir um servidor de Factorio! ⚙️

Mas, Gabriel, eu não gosto de Factorio!

Ótimo! Melhor ficar longe desse vício.

O factorio é só um exemplo, e é a parte menos importante do guia. Explicarei como fazer isso para outros jogos (e.g. minecraft), continue lendo!

O versão final está disponível aqui: GitHub - Misterio77/hackathon-mgc-factorio-terraform. Esse tutorial irá mostrar como construir esse código iterativamente.

Intro 🏁

O NixOS é uma distribuição Linux baseada no gerenciador de pacotes Nix. O Nix permite empacotar programas de forma reproduzível e isolada, numa linguagem declarativa e pura. O NixOS leva isso a um outro nível, e permite configurar sistemas inteiros usando essa mesma linguagem. Por exemplo, para subir um servidor de Factorio:

{
  services.factorio = {
    enable = true;
  };
}

Lembra bastante o Terraform, né?

Vou mostrar pra vocês como implantar e configurar um servidor no Magalu Cloud, via Terraform e NixOS, por meio do nixos-anywhere.

A idéia é que, com apenas um tofu apply, o servidor seja criado já rodando exatamente o que você quer que rode, sem nenhum passo manual. 👷

Mãos à obra!

Setup 🔨

Caso queira acompanhar o tutorial e ir rodando coisas na sua máquina (que recomendo!), você vai precisar:

Qualquer distro Linux (pode ser WSL) ou MacOS;
Instalar o gerenciador de pacotes Nix (sua máquina não precisa ser NixOS);
Instalar a MGC CLI;
Instalar o OpenTofu;
Uma chave SSH;
Um editor de texto que você goste.

Configuração de NixOS ❄️

Para usarmos algumas funcionalidades novas do Nix, vamos habilitar flakes e nix-command:

$ mkdir -p ~/.config/nix
$ echo "extra-experimental-features = nix-command flakes" >> ~/.config/nix/nix.conf

Vamos começar configurando nosso NixOS. Crie uma configuration.nix:

{
  networking = {
    hostName = "factorio-server";
    # Usar DHCP para conectar
    useDHCP = true;
  };

  system.stateVersion = "25.05";
  nixpkgs = {
    # Arquitetura e sistema
    hostPlatform = "x86_64-linux";
    # Habilitar pacotes proprietários
    config.allowUnfree = true;
  };

  services.factorio = {
    enable = true;
    # Abrir porta no firewall
    openFirewall = true;
  };

  # TODO: Iremos remover isso depois
  users.users.root = {
    initialPassword = "123456";
  };
}

Gabriel, o que mais podemos rodar além de factorio?

O que seu coração mandar! O NixOS tem abstrações prontas para vários jogos, e você pode rodar qualquer software que imaginar. Experimente services.minecraft!

Vamos usar flakes nesse tutorial. Crie uma flake.nix:

{
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
  };

  outputs = { nixpkgs, ... }: {
    nixosConfigurations.factorio-server = nixpkgs.lib.nixosSystem {
      modules = [./configuration.nix];
    };
  };
}

Gabriellll, o que é diachos é um flake?

Ótima pergunta! Ter um flake.nix torna seu repositório um flake (duh). Em resumo, um flake é um “projeto nix”, com dependências em outros “projetos nix”, e que provê “coisas nix”. Nesse caso, nosso projeto depende do nixpkgs (o conjunto principal de software empacotado para Nix) na versão nixos-unstable, e provê uma configuraçao de NixOS chamada factorio-server.

É possível usar Nix sem flakes, mas criar um flake te permite gerir melhor as dependências do seu projeto e usar uma CLI mais intuitiva.

Vamos testar? O Nix permite criar uma VM para uma dada configuração de NixOS. Rode:

$ nix run .#nixosConfigurations.factorio-server.config.system.build.vm

Pode levar alguns minutos, pois o Nix irá baixar absolutamente tudo nescessário para esse sistema. Fique tranquilo, pois seu sistema irá re-usar isso sempre que possível.

Irá abrir uma janela com o console da sua VM. Faça login com root e 123456.

Vamos ver se o servidor está okay:

systemctl status factorio

Sucesso! Nossa VM está rodando Factorio ⚙️

Agora, vamos colocar isso na Cloud! Bora para o Terraform. Depois voltaremos para fazer alguns ajustes nessa configuração.

Subindo VM com Terraform ☁️

Crie um arquivo main.tf, com o conteúdo:

terraform {
  backend "local" {
    path = ".terraform.tfstate"
  }
  required_providers {
    mgc = {
      source = "registry.terraform.io/magalucloud/mgc"
      version = "0.36.1"
    }
  }
}

provider "mgc" {
  region = "br-se1"
}

Nice. Esse é o nosso boilerplate básico pra usar o provider e manter o estado do terraform no nosso diretório local.

O terraform lê todas as .tf no diretório, então vamos deixar as coisas organizadinhas.

Criando a VM

Vamos preparar nossa VM. Crie um vm.tf:

resource "mgc_virtual_machine_instances" "factorio_server" {
  name = "factorio"
  # 2 vCPUs, 8GB de RAM, 40GB de disco
  machine_type = "BV2-8-40"
  image = "cloud-debian-12 LTS"
}

Ué, Debian? Não íamos usar NixOS? Que sacrilégio é esse?

Calma calma foguetinho 🚀! O Magalu Cloud ainda não tem imagem de NixOS, mas temos uma carta na manga para instalar e configurar o NixOS, aguenta ai!

Tornando ela acessível ao mundo

Precisamos acessar essa VM. Pra isso, vamos:

Adicionar nossa chave SSH
Alocar um IP público e atribuir ele à máquina
Abrir a porta do SSH (22 TCP) e do Factorio (34197 UDP) no firewall da cloud

Começando pela chave pública. Na sua vm.tf:

resource "mgc_ssh_keys" "key" {
  name = "chave-do-gabriel"
  # Altere para a sua chave publica
  key = "<SUA CHAVE SSH PUBLICA>"
}

resource "mgc_virtual_machine_instances" "factorio_server" {
  name = "factorio"
  # 2 vCPUs, 8GB de RAM, 40GB de disco
  machine_type = "BV2-8-40"
  image = "cloud-debian-12 LTS"
  # Passar nossa chave
  ssh_key_name = mgc_ssh_keys.key.name
}

E vamos alocar um IPv4 dedicado e atribuir à maquina, crie uma ip.tf:

# Alocar um IPv4
resource "mgc_network_public_ips" "factorio_ip" {
  vpc_id = mgc_virtual_machine_instances.factorio_server.vpc_id
}

# Atribuir à máquina
resource "mgc_network_public_ips_attach" "factorio_ip_attach" {
  public_ip_id = mgc_network_public_ips.factorio_ip.id
  interface_id = mgc_virtual_machine_instances.factorio_server.network_interfaces[0].id
}

# O terraform vai mostrar esse valor para nós
output "ip" {
  value = mgc_network_public_ips.factorio_ip.public_ip
}

Por fim, vamos abrir as portas. Crie uma firewall.tf:

# Nosso security group
resource "mgc_network_security_groups" "factorio_server" {
  name = "factorio-hackathon"
}

# Regra para SSH
resource "mgc_network_security_groups_rules" "incoming_ssh" {
  direction = "ingress"
  port_range_min = 22
  port_range_max = 22
  protocol = "tcp"
  ethertype = "IPv4"
  remote_ip_prefix = "0.0.0.0/0"
  security_group_id = mgc_network_security_groups.factorio_server.id
}
# Regra para o factorio
resource "mgc_network_security_groups_rules" "incoming_factorio" {
  direction = "ingress"
  port_range_min = 34197
  port_range_max = 34197
  protocol = "udp"
  ethertype = "IPv4"
  remote_ip_prefix = "0.0.0.0/0"
  security_group_id = mgc_network_security_groups.factorio_server.id
}

# Atribuir o group à nossa VM
resource "mgc_network_security_groups_attach" "factorio_firewall_attach" {
  security_group_id = mgc_network_security_groups.factorio_server.id
  interface_id      = mgc_virtual_machine_instances.factorio_server.network_interfaces[0].id
}

Lembre-se de trocar (ou adicionar) regras conforme o que você está deployando. Por exemplo, se está subindo minecraft, faça uma regra que abre a porta 25565 no protocolo tcp.

O primeiro deploy

Maravilha! Hora de deployar. Vamos começar autenticando via MGC CLI:

$ mgc auth login

E siga os passos na tela.

Agora precisamos criar uma API key e passar para o terraform.

$ mgc auth api-key create --name terraform-factorio

Aperte a flecha direita para dar todas as permissões, e tab para aceitar. Agora vamos pegar a key e passar para o terraform. Um oneliner que facilita:

export TF_VAR_mgc_api_key=$(mgc auth api-key get --id $(mgc auth api-key list -o json -r | jq 'map(select(.name == "terraform-factorio"))[0].id' -r) -o json -r | jq .api_key -r)

Feito isso, vamos preparar o terraform:

$ tofu init

E aplicar:

$ tofu apply

Digite yes, e aguarde um pouquinho.

Feito isso, é hora de validar que o servidor está okay e está acessível pela sua chave. O seu apply deve ter retornado o ip como output. Rode:

$ ssh debian@<IP DA VM>

Agora temos uma VM… Rodando Debian (por enquanto):

Vamos agora infectar essa querida com NixOS! Iremos utilizar o nixos-anywhere.

Instalando NixOS na VM 🪄

A idéia do nixos-anywhere é iniciar um NixOS via kexec, desmontar o disco da máquina, re-particionar ele, e instalar NixOS de verdade (com a nossa configuração). Eles provêm um módulo de Terraform, que é perfeito para a gente!

Gabriel, kexec? Que diacho é isso?

Não tema! É bem mais simples do que parece. Significa “kernel execute”.

Pense assim: quando você vai instalar Linux numa máquina, você geralmente boota uma ISO por pendrive. Isso é necessário para você poder liberar e formatar o disco do seu computador.

No Magalu não temos como espetar um pendrive, então usamos um truque de executar outro Linux direto na memória RAM da máquina, isso nos permite desmontar e formatar os discos da máquina, igual com um pendrive!

Vamos precisar fazer alguns ajustes na nossa configuração de NixOS para comportar isso. O NixOS anywhere usa uma ferramenta chamada disko para particionar declarativamente. Vamos adicioná-la no nosso flake.nix:

{
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
    disko.url = "github:nix-community/disko/latest";
    disko.inputs.nixpkgs.follows = "nixpkgs";
  };

  outputs = { nixpkgs, disko, ... }: {
    nixosConfigurations.factorio-server = nixpkgs.lib.nixosSystem {
      modules = [
        ./configuration.nix
        disko.nixosModules.disko
      ];
    };
  };
}

Rode:

$ nix flake lock

Para registrar a mudança na flake.lock.

Nice. Agora vamos adicionar as configurações específicas da máquina (partições, módulos de kernel). Vamos fazer isso num arquivo separado da configuration.nix, para separar o “what it runs” e o “where it runs”.

Crie um arquivo hardware-configuration.nix:

{modulesPath, ...}: {
  imports = [(modulesPath + "/profiles/qemu-guest.nix")];
  boot = {
    initrd.availableKernelModules = ["ata_piix" "uhci_hcd"];
    kernelModules = ["kvm-intel"];
  };

  # Nossas partições
  disko.devices.disk.main = {
    device = "/dev/vda";
    type = "disk";
    content = {
      type = "gpt";
      partitions = {
        boot = {
          size = "1M";
          type = "EF02";
        };
        esp = {
          size = "512M";
          type = "EF00";
          content = {
            type = "filesystem";
            format = "vfat";
            mountpoint = "/boot";
          };
        };
        root = {
          size = "100%";
          content = {
            type = "filesystem";
            format = "ext4";
            mountpoint = "/";
          };
        };
      };
    };
  };
}

Não se preocupe muito se isso parece complexo. A maior parte desse arquivo foi gerado automaticamente. A parte do disko define quais nossas partições.

Precisamos importar esse arquivo da nossa configuration.nix. Também vamos tirar a senha 123456, e habilitar SSH. Edite ela:

{
  imports = [
    ./hardware-configuration.nix
  ];

  networking = {
    hostName = "factorio-server";
    useDHCP = true;
  };

  system.stateVersion = "25.05";
  nixpkgs = {
    hostPlatform = "x86_64-linux";
    config.allowUnfree = true;
  };

  services.factorio = {
    enable = true;
    openFirewall = true;
  };

  services.openssh = {
    enable = true;
    settings = {
      PermitRootLogin = "yes";
      PasswordAuthentication = false;
    };
  };

  users.users.root = {
    openssh.authorizedKeys.keys = [
      # Troque para sua chave.
      "<SUA CHAVE SSH PUBLICA>"
    ];
  };
}

Lembre-se de trocar a chave SSH para a sua.

Gabriel, por que temos a chave SSH em dois lugares?

A do terraform define qual vai ser a chave autorizada assim que a máquina é provisionada. Essa chave será usada pela instalação inicial do nixos-anywhere. A do NixOS é qual será a chave autorizada após a instalação (e nescessária para rebuilds). No repositório (link no fim do post), fizemos de um jeito mais robusto: o terraform cria a chave.

Certo, agora vamos configurar o nixos-anywhere pelo terraform. Crie um nixos.tf:

module "deploy" {
  source = "github.com/nix-community/nixos-anywhere//terraform/all-in-one"
  nixos_system_attr = ".#nixosConfigurations.factorio-server.config.system.build.toplevel"
  nixos_partitioner_attr = ".#nixosConfigurations.factorio-server.config.system.build.diskoScript"
  debug_logging = true

  instance_id = mgc_virtual_machine_instances.factorio_server.id
  target_host = mgc_virtual_machine_instances.factorio_server.network.public_address
  install_user = "debian"
}

Adicionamos um novo módulo externo, então rode novamente o init:

$ tofu init

Certinho! Estamos prontos. Vamos aplicar a configuração do Terraform:

$ tofu apply

Aguarde alguns minutos (geralmente menos de 5). O NixOS anywhere irá instalar NixOS na VM, e aplicar nossa configuração!

Sempre que você modificar a configuração, basta dar apply novamente, ele irá detectar a mudança e fazer alterações na VM conforme nescessário.

Sucesso! Podemos usar o IP agora para jogar factorio:

Fechamento

Espero que esse tutorial tenha ajudado você a ver algumas das coisas que são possíveis no modelo declarativo!

A magia da coisa é que qualquer um pode rodar tofu apply e ter um servidor exatamente igual. Fazendo as mudanças nos arquivos e rodando apply, você garante que não existe nenhum passo de setup (e.g. instale coisa X, altere arquivo Y) além de simplesmente ter os arquivos .tf e .nix.

O versão final está disponível no repositório: GitHub - Misterio77/hackathon-mgc-factorio-terraform

Feedback é muito bem vindo, e fico a disposição para qualquer dúvida!

Beijos, Gab

How to package a Rust app using Nix

Tue, 01 Nov 2022 00:00:00 +0000

Sometimes I see people looking around for a cookbook to package a rust project. Here’s a simple way to do it. As a plus, I’ll also show how to export the package through a flake.

I’ll use nixpkgs’ buildRustPackage. There’s a few other tools, my favorite being crate2nix, but we’ll leave that to a future tutorial.

Note: In this tutorial, we’ll be nixifying a crate on its own repo. If you want to package it elsewhere, remember to use fetchFromGitHub (and friends) with src instead of lib.cleanSource ./.;

Ready, set, go!

Let’s start by scaffolding a rust project with cargo:

nix run nixpkgs#cargo init foo-bar
cd foo-bar

Let’s also generate a Cargo.lock:

nix run nixpkgs#cargo update

And stage the files so that Nix sees them:

git add .

Okay, start by creating a default.nix file and add this minimal example:

{ pkgs ? import <nixpkgs> { } }:
pkgs.rustPlatform.buildRustPackage rec {
  pname = "foo-bar";
  version = "0.1";

  cargoLock.lockFile = ./Cargo.lock;

  src = pkgs.lib.cleanSource ./.;
}

Now let’s build it:

# Nix3 command
nix build -f default.nix
# The nix legacy command also works
nix-build default.nix

I swear. That’s really what you need for a working package. Nix’s happy path is really happy.

./result/bin/foo-bar
# Hello, world!

Flakefy it!

Let’s add a flake.nix now. Here’s a minimal example:

{
  description = "Foo Bar";

  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
  };

  outputs = { self, nixpkgs }:
    let
      supportedSystems = [ "x86_64-linux" ];
      forAllSystems = nixpkgs.lib.genAttrs supportedSystems;
      pkgsFor = nixpkgs.legacyPackages;
    in {
      packages = forAllSystems (system: {
        default = pkgsFor.${system}.callPackage ./. { };
      });
    };
}

Add any systems you want to support to supportedSystems list, of course.

The build is now more reproducible, as it will use the nixpkgs commit locked into flake.lock:

nix build

You even get a dev shell for free:

nix develop

Augment our dev shell

Let’s say you want additional tooling, such as a LSP, a formatter, a linter… You can augment this shell with additional packages!

Create a shell.nix file:

{ pkgs ? import <nixpkgs> { } }:
pkgs.mkShell {
  # Get dependencies from the main package
  inputsFrom = [ (pkgs.callPackage ./default.nix { }) ];
  # Additional tooling
  buildInputs = with pkgs; [
    rust-analyzer # LSP Server
    rustfmt       # Formatter
    clippy        # Linter
  ];
}

Nice. Let’s try it:

# Nix3 command
nix develop -f shell.nix
# Nix legacy command
nix-shell shell.nix

Note: If you use a shell other than bash and want to use nix develop with it, append a -c $SHELL to the command.

Awesome, we have augmented our shell with additional rust tooling :)

Let’s add it to our flake:

{
  description = "Foo Bar";

  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
  };

  outputs = { self, nixpkgs }:
    let
      supportedSystems = [ "x86_64-linux" ];
      forAllSystems = nixpkgs.lib.genAttrs supportedSystems;
      pkgsFor = nixpkgs.legacyPackages;
    in {
      packages = forAllSystems (system: {
        default = pkgsFor.${system}.callPackage ./default.nix { };
      });
      devShells = forAllSystems (system: {
        default = pkgsFor.${system}.callPackage ./shell.nix { };
      })
    };
}

I’ve replaced ./. with ./default.nix to make it more explicit.

Calling it is easier and more reproducible now:

nix develop

Grab metadata automagically

Setting the metadata (name, version) on two separate places (Cargo.toml and default.nix) is boring, we can do better! Let’s try out importTOML in our default.nix:

{ pkgs ? import <nixpkgs> { } }:
let manifest = (pkgs.lib.importTOML ./Cargo.toml).package;
in
pkgs.rustPlatform.buildRustPackage rec {
  pname = manifest.name;
  version = manifest.version;

  cargoLock.lockFile = ./Cargo.lock;

  src = pkgs.lib.cleanSource ./.;
}

Nice.

Closing thoughts

AFAIK, this is the simplest way to package Rust crates. This should also make the project acessible for both flake/nix3 users and for those who still use nix-build and nix-shell.

I decided to keep this focused on buildRustPackage that, while simple and vanilla, has a few drawbacks (such as rebuilds starting from scratch). If you’re interested in incremental building, keep tuned: I will probably make a post about crate2nix soon(tm).

Spotted an error? See something I should improve or reword? Let me know at hi@m7.rs!

Hello World

Tue, 08 Jun 2021 00:00:00 +0000

Here’s a writeup on how i made this website

Notice: this website has evolved quite a lot since this post, this might not be up to date

I’ve been wanting to get into blogging random tech rants, maybe something useful too. Guides, maybe?

Well, i kept putting this off for quite a while, as i just couldn’t decide which way to build it. I’ve considered the big frameworks, server side rendering, handwritting static assets, all the stuff.

Okay. So (as you can see) i got it done and i’m writing my first blog entry, about the blog itself.

How did i build it?

Semantic HTML and 170+ CSS schemes

I decided to start building the about page as a purely static page. I was looking for a good and pure CSS library i could use, as to keep the site as simple and lightweight as possible, considering i don’t need any dynamic content.

First, i’m not a huge fan of utility CSS or heavily class based HTML. In my opinion, HTML should have as much semantic meaning as possible, and not be concerned with how a CSS sheet does the styling. I also love markdown, and i like having a 1:1 conversion from it to HTML, without having to add stuff. Blogging in markdown was big on the site wishlist.

Second, although they might be useful (specially when CSS did not support variables), i prefer to use CSS variables (root level custom properties) instead of preprocessors such as sass.

My reason for this is my aim of using base16 schemes to dynamically theme my website (170+ themes!) in a lazy way. That is, only loading any specific scheme on demand. Using a preprocessor would end up in generating full CSS sheets for each scheme option, which is not very bandwidth effective.

There’s a plethora of different ways to offer schemes to a user. I did it by factoring out all colors on my base CSS sheet to variables, and using flavours to generate a CSS sheet (with just the 16 color variables) for each existing scheme. These can be selected using a input field (check the palette button at the top), and will set a link tag’s href value to the scheme, taking precedence over the default two schemes (one light and one dark, for prefers-color-scheme: dark) i specified on the base sheet.

With that done, i also set a tiny localStorage key to the browser, so the scheme preference can be persisted across visits.

Here’s a code snippet:

let chosen_scheme_css = document.getElementById("chosen-scheme");

// Set a given scheme
function setTheme(scheme) {
chosen_scheme_css.setAttribute(
  "href",
  "/assets/schemes/" + scheme + ".css"
);
localStorage.setItem("current-scheme", scheme);
}
// Reset scheme to defaults (rose-pine moon or dawn, depending on preference)
function resetTheme() {
chosen_scheme_css.removeAttribute("href");
localStorage.removeItem("current-scheme");
}

// Get stored scheme from localStorage and reapply it
let stored_scheme = localStorage.getItem("current-scheme");
if (stored_scheme) {
setTheme(stored_scheme);
}

This seems to me a very simple and clean way of doing it, without introducing complicated JS libraries to the equation. The colors even fade based on animation CSS property!

A simple CSS styling

With that in mind, i set out to search for a minimal and semantic CSS sheet, preferably one using CSS variables.

Checking a few lists, i found water.css, and it ticked all the boxes. It looks absolutely beautiful and is pure CSS.

All i had to do get my theming working was three link elements, which import, in order:

Water.css
My own sheet, which maps base0x variables to water.css ones, and provides two default schemes
The user defined color scheme, once set (has an empty href by default)

Code reuse and markdown pages

Okay, that’s good enough for a personal website with a single page. But what if i want other pages with the same common elements, such as the navbar, the scheme dialog, footer… We would have to duplicate everything, ending up in a huge amount of duplicated HTML code, and a lot of pain to make changes everywhere at once.

Fetching content at runtime from a full fledged server and database is little overkill for a blog that i update once in a blue moon. When we don’t need user generated data, adding content to the website at compile time makes a lot more sense. Enter Static Site Generation, or SSG.

Again, another problem of complete solutions is flexibility. I already have my styling and structure set, i just wanted a simple tool to factor out duplicated code. I stumbled upon Jekyll and its simplistic and modular goodness.

Jekyll is very straightforward and doesn’t force you to change everything to support it. It works with templating (liquid) and markdown rendering. You can factor out common stuff from your website into includes (that work kinda like componentes) or layouts. All of this gets built into static assets, it doesn’t get in your way and works great. It’s also worth mentioning that most of the features are opt-in, you don’t have to change absolutely nothing from your static assets if you don’t want to.

Automating style building

One of (the most useful, i think) my little projects is called flavours. It’s a unixy CLI tool that downloads and builds color schemes and templates that follow the base16 standard.

It’s mostly built for people that use heavily customizable desktop programs (terminals, window managers, status bars, etc). The ideia is setting up just once, and them instantly theming your entire setup with any base16 scheme, by replacing delimiters inside text configuration files (people call them dots). Schemes are really easy to make (flavours can even generate them from images, usually wallpapers), so this allows the power of infinite color schemes on a desktop.

It also works as a standard base16 builder, replacing scheme variables inside templates and outputting them. There’s a CSS variables template, so it’s really easy to generate a CSS sheet for hundreds of different schemes. Here’s how that template looks:

/* {{scheme-name}} by {{scheme-author}} */
:root {
  --base00: #{{base00-hex}};
  --base01: #{{base01-hex}};
  --base02: #{{base02-hex}};
  --base03: #{{base03-hex}};
  --base04: #{{base04-hex}};
  --base05: #{{base05-hex}};
  --base06: #{{base06-hex}};
  --base07: #{{base07-hex}};
  --base08: #{{base08-hex}};
  --base09: #{{base09-hex}};
  --base0A: #{{base0A-hex}};
  --base0B: #{{base0B-hex}};
  --base0C: #{{base0C-hex}};
  --base0D: #{{base0D-hex}};
  --base0E: #{{base0E-hex}};
  --base0F: #{{base0F-hex}};
}

Pretty simple, huh? The spec provides those placeholders, which can be used in virtually any kind of file that specifies colors.

Here’s how it looks with a color scheme (pasque) applied:

/* Pasque by Gabriel Fontes (https://github.com/Misterio77) */
:root {
  --base00: #271C3A;
  --base01: #100323;
  --base02: #3E2D5C;
  --base03: #5D5766;
  --base04: #BEBCBF;
  --base05: #DEDCDF;
  --base06: #EDEAEF;
  --base07: #BBAADD;
  --base08: #A92258;
  --base09: #918889;
  --base0A: #804ead;
  --base0B: #C6914B;
  --base0C: #7263AA;
  --base0D: #8E7DC6;
  --base0E: #953B9D;
  --base0F: #59325C;
}

So, how do we generate one for every existing scheme? Additionally, there’s a HTML tag datalist that allows for suggestions on an input form element. Maybe we can build one so the user knows which schemes are available?

Of course. flavours allows for great scriptability, so just use a bash script:

datalist_file="_includes/scheme-datalist.html"
template_path=~/.local/share/flavours/base16/templates/styles/templates/css-variables.mustache

# Add datalist opening tag
echo -n "<datalist id=\"scheme-list\">" > $datalist_file
# For each scheme
flavours list -l | while read slug; do
    # Get scheme file path
    scheme_path=$(flavours info $slug | head -1 | cut -d '@' -f2)
    # Build scheme
    flavours build $scheme_path $template_path > assets/schemes/$slug.css
    # Add entry to datalist
    echo -n "<option>$slug</option>" >> $datalist_file
done
# Add datalist closing tag
echo "</datalist>" >> $datalist_file

This script basically uses flavours list to get a list of all installed schemes and iterates over them. For each scheme, we build the css-variables template with it, outputting to the assets directory, and add its slug to the file with <datalist>.

Wrapping up

Okay, this was my first blog entry, and that’s how my simpl(ish) and minimalist site works. Feel free to check the source code to learn more, or grab something for your own use (everything’s MIT licensed).

Here’s a few links to the stuff i used:

water.css (base CSS styling)
prism.js (code highlighting library)
jekyll (static page generator)
base16 (color theme spec)
flavours (base16 builder)