Spoljarevic's Knowledgebase

Impressum

Mon, 01 Jan 0001 00:00:00 +0000

Inhalte gemäß § 5 DDG

Luca Matteo Špoljarević
c/o IP-Management #12320
Ludwig-Erhard-Straße 18
20459 Hamburg

Kontaktdaten:

E-Mail: webadmin@info.spoljarevic.sh
Telefon: +49 7141 493 34 21

Umsatzsteuer-Identifikationsnummer gemäß § 27a UStG:

DE457678112

Redaktionell verantwortlich:

Luca Matteo Špoljarević

Introduction

Mon, 01 Jan 0001 00:00:00 +0000

Arch Linux Post-Install Automation is an Ansible playbook that takes a fresh Arch Linux (or Arch-based, e.g. CachyOS) install and turns it into a fully configured daily-driver machine — without manually installing packages, enabling services, or configuring your shell one by one.

What it does

Run against a target host, the playbook will:

Bootstrap the CachyOS and BlackArch pacman repositories
Install a full package set via pacman, the AUR (via yay), Flatpak, and Snap
Apply basic system hardening (firewalld, fail2ban, doas, a non-default SSH port, disabled password authentication)
Create a standard set of user directories (Documents, Downloads, Pictures/wallpaper, git, …)
Install and configure Zsh with Oh My Zsh, Powerlevel10k, and a Nerd Font
Generate SSH and GPG keys and configure git for signed commits
Clone a set of personal repositories (dotfiles, wallpapers, other projects)

Why it exists

Re-installing Arch (or setting up a new machine) used to mean an hour or more of repetitive manual setup. This playbook exists so that process is a single command: point Ansible at a host, get a coffee, and come back to a fully configured system.

Introduction

Mon, 01 Jan 0001 00:00:00 +0000

What is FreePBX?

FreePBX is an open-source web GUI for Asterisk, the PBX/VoIP engine that underpins it. Asterisk on its own is configured through plain-text dialplan files; FreePBX wraps it in a web interface for managing extensions, trunks, inbound/outbound routes, IVRs, voicemail, and the rest of what a phone system needs, without hand-editing Asterisk config. Version 17 is the current release line, built on Asterisk 22 and PHP 8.2.

Introduction

Mon, 01 Jan 0001 00:00:00 +0000

What is Zammad?

Zammad is an open-source ticket system. A ticket system is essential for any IT sysadmin — it organizes user problems into tickets and lets you document everything you did to solve them, instead of losing that history in email or chat.

What are Quadlets?

Quadlets are a Podman feature that lets you describe containers, pods, networks, and volumes as native systemd unit files. systemd generates the actual .service units from them at boot/login, so Podman containers get managed exactly like any other systemd service — restarted on failure, started in dependency order, and started automatically without a separate compose daemon running in the background.

Introduction

Mon, 01 Jan 0001 00:00:00 +0000

What is lazy.nvim?

lazy.nvim is a plugin manager for Neovim. It handles cloning, updating, and lazy-loading plugins from a set of declarative “specs” — Lua tables that say which plugin to install, what triggers it to load (a command, a keymap, a filetype, an event), and how to configure it once loaded.

What this is

A Neovim configuration written entirely from scratch on top of lazy.nvim — every option, keymap, and plugin spec here was written by hand, plugin by plugin. It is not the LazyVim distribution, and doesn’t depend on it. Distributions like LazyVim or kickstart.nvim ship pre-built, opinionated defaults (LSP presets via nvim-lspconfig’s setup functions, a formatter framework, a fixed plugin set); this config instead wires each piece directly, which means more to write, but nothing hidden behind a distribution’s abstractions.

Datenschutzerklärung

Mon, 01 Jan 0001 00:00:00 +0000

English version

1. Verantwortlicher

Verantwortlich für die Datenverarbeitung auf dieser Website im Sinne der Datenschutz-Grundverordnung (DSGVO) ist:

Luca Matteo Špoljarević
c/o IP-Management #12320
Ludwig-Erhard-Straße 18
20459 Hamburg
E-Mail: webadmin@info.spoljarevic.sh

2. Das Wichtigste in Kürze

Diese Website ist eine rein statische Website. Es gibt keine Benutzerkonten, keine Kontaktformulare, keinen Newsletter, keine Analyse- oder Tracking-Tools, keine Werbung und diese Website setzt keine Cookies. Schriftarten und Skripte werden nicht von fremden Servern nachgeladen.

Usage

Mon, 01 Jan 0001 00:00:00 +0000

Prerequisites

A control machine with Ansible installed.
A target host running Arch Linux (or an Arch-based distro such as CachyOS), reachable over SSH with a user that can become root (sudo).

Warning

This playbook is built for Arch Linux specifically — it uses pacman, and adds CachyOS/BlackArch repositories. Running it against a different distribution will fail.

1. Install required Ansible collections

The playbook depends on a few community Ansible collections:

Usage

Mon, 01 Jan 0001 00:00:00 +0000

Prerequisites

Docker and Docker Compose (docker-compose or the docker compose plugin) on the host.
A host willing to run a privileged container — this setup needs --privileged and an unconfined seccomp profile for systemd to manage services inside the container.

1. Clone the repository and build the image

git clone https://codeberg.org/Spoljarevic/FreePBX-17-Container.git
cd FreePBX-17-Container
sudo docker-compose build

The build stage (see Code Explanation) only installs the OS-level prerequisites and copies in the install script — FreePBX itself is not installed at build time.

Usage

Mon, 01 Jan 0001 00:00:00 +0000

Prerequisites

A recent Podman version with Quadlet support (Podman 4.4+; check with podman --version).
systemd (used both as the rootless user’s systemd --user instance and, optionally, system-wide).

1. Configure your environment

Copy the example environment file and fill in your own values:

cp .env.example .env
$EDITOR .env

At minimum, review and change the database/Elasticsearch credentials (POSTGRES_PASS, ELASTICSEARCH_PASS), ZAMMAD_FQDN, TZ, and the backup schedule (BACKUP_TIME, HOLD_DAYS). Everything under “PROXY / EXTERNAL ACCESS” and “Cloudflare Tunnel” in .env.example is optional and commented out by default.

Usage

Mon, 01 Jan 0001 00:00:00 +0000

Deployment

There’s no separate install step for this config specifically — it’s deployed as part of the Dotfiles monorepo. ~/.config is a symlink to the root of that repository, so nvim/ inside it automatically becomes ~/.config/nvim, which is where Neovim looks for its config by default.

Note

This means editing ~/.config/nvim/lua/plugins/foo.lua and editing this repo’s nvim/lua/plugins/foo.lua are the same file.

First launch

nvim

On the very first run, lua/config/lazy.lua detects that lazy.nvim itself isn’t installed yet, clones it into Neovim’s data directory, and then installs every plugin declared under lua/plugins/*.lua. Subsequent launches just load already-installed plugins.

Code Explanation

Mon, 01 Jan 0001 00:00:00 +0000

Repository layout

archPostInstall.yml the full playbook — every play, in order
spo-pc-ls.yml ansible-vault encrypted secrets (not usable by others as-is)
inventory.ini example Ansible inventory
requirenments.yml Ansible Galaxy collection dependencies
snippets/ the same plays, split into standalone, individually runnable playbooks

Note

The dependencies file is named requirenments.yml (not requirements.yml) — use that exact filename when installing collections.

`archPostInstall.yml`

This is the “run everything” entrypoint. It’s a sequence of independent Ansible plays, executed top to bottom:

Code Explanation

Mon, 01 Jan 0001 00:00:00 +0000

`Dockerfile`

FROM debian:bookworm
...
RUN apt-get update && apt-get install -y \
 wget curl gnupg2 sudo git vim ca-certificates lsb-release software-properties-common \
 systemd systemd-sysv dbus net-tools openssh-client \
 && apt-get clean
WORKDIR /usr/src
COPY sng_freepbx_debian_install.sh .
RUN chmod +x ./sng_freepbx_debian_install.sh
RUN ln -s /var/lib/asterisk/bin/fwconsole /usr/sbin/fwconsole || true
EXPOSE 80 443 5060/udp 5160/udp 18000-18100/udp
CMD ["/bin/bash"]

The image is deliberately thin:

Base: debian:bookworm — Sangoma’s install script hard-codes support for Debian 12 only (it checks VERSION_CODENAME//etc/debian_version and exits if it isn’t bookworm).
Installed at build time: only systemd/systemd-sysv/dbus (so the container can boot like a real init system) plus generic tooling the install script or an admin would want (wget, curl, git, vim, etc). FreePBX, Asterisk, MariaDB, Apache, and PHP are not installed here — that all happens later, at container runtime, by running the copied-in script manually.
The fwconsole symlink: fwconsole is FreePBX’s CLI (module management, restarts, etc). The install script normally expects it at a path that isn’t always on PATH yet immediately after install in a fresh container; the symlink into /usr/sbin pre-empts that so fwconsole works without extra steps once FreePBX is installed. The || true makes the build tolerant of the target not existing yet at build time.
CMD ["/bin/bash"]: the image’s default command is just a shell — the actual PID 1 process is overridden by docker-compose.yml’s command: ["/sbin/init"], not this line.

Installing FreePBX at build time isn’t possible here: the installer needs a running init system managing services (systemctl), which only exists once the container is actually started, not while docker build is assembling image layers.

Code Explanation

Mon, 01 Jan 0001 00:00:00 +0000

Anatomy of a Quadlet unit

Every .container file in this repo follows the same shape:

[Unit]
After=zammad.pod ... # start order
Requires=zammad.pod ... # hard dependency
PartOf=zammad.pod # stop/restart together with the pod

[Container]
Image=...
ContainerName=...
Pod=zammad.pod # joins the shared pod network namespace
Exec=... # command run inside the Zammad image for this role
EnvironmentFile=.env

[Service]
Restart=always
RestartSec=...

[Install]
WantedBy=default.target # lets systemctl enable start it at boot/login

PartOf=zammad.pod means stopping or restarting the pod stops/restarts the container with it. Pod=zammad.pod puts every container in the same network namespace, so they can reach each other over localhost instead of needing container-to-container DNS.

Code Explanation

Mon, 01 Jan 0001 00:00:00 +0000

Load order

init.lua is four requires, executed in order:

require("config.options")
require("config.lazy")
require("config.keymaps")
require("config.autocmds")

config/options.lua — plain vim.o.* settings (line numbers, relative numbers, mouse support, split direction, 2-space indentation, etc). No plugins involved.
config/lazy.lua — bootstraps lazy.nvim itself: if it isn’t already cloned into Neovim’s data directory, git clones it, prepends it to the runtimepath, then calls require("lazy").setup("plugins", { change_detection = { notify = false } }). That call auto-discovers and loads every spec file under lua/plugins/*.lua — adding a new plugin is just adding a new file there, no manual registration step.
config/keymaps.lua — global keymaps, centralized here rather than scattered per-plugin file (see Usage for the full table).
config/autocmds.lua — currently just the format-on-save autocmd.

Plugin spec files

Each file under lua/plugins/ returns a lazy.nvim spec table (or a list of tables), and filenames map roughly 1:1 to the plugin they configure:

Privacy Policy

Mon, 01 Jan 0001 00:00:00 +0000

This is a translation for convenience. The German version is legally binding.

1. Controller

The controller responsible for data processing on this website under the General Data Protection Regulation (GDPR) is:

Luca Matteo Špoljarević
c/o IP-Management #12320
Ludwig-Erhard-Straße 18
20459 Hamburg, Germany
Email: webadmin@info.spoljarevic.sh

2. Summary

This is a purely static website. There are no user accounts, no contact forms, no newsletter, no analytics or tracking tools, no advertising, and this website sets no cookies. Fonts and scripts are not loaded from third-party servers.

FAQ

Mon, 01 Jan 0001 00:00:00 +0000

Can I run this on a different distro?

No. It relies on pacman, and specifically bootstraps the CachyOS and BlackArch pacman repositories. It will not work on Debian/Fedora/etc.

Do I have to run the entire playbook?

No — run only what you need via the standalone playbooks in snippets/. See Code Explanation for the full list, and Usage for an example command.

FAQ

Mon, 01 Jan 0001 00:00:00 +0000

Why does the container need `privileged: true`?

Because it runs systemd as PID 1, and systemd needs privileges Docker doesn’t grant by default (managing cgroups, mounting filesystems, controlling devices) to supervise the services FreePBX depends on — Apache, MariaDB, Asterisk. Without it, /sbin/init won’t boot cleanly inside the container. See Introduction for the trade-off this implies.

Why isn’t FreePBX installed automatically when I build the image?

Sangoma’s install script assumes it’s running on an already-booted system with a working init system managing services — that’s only true once the container is actually running, not while docker build is assembling layers. So the build stage only prepares the environment (Debian + systemd + the script itself); you run the installer yourself after docker-compose up -d. See Usage for the exact steps.

FAQ

Mon, 01 Jan 0001 00:00:00 +0000

Why Quadlets instead of `docker-compose` / `podman-compose`?

Quadlets translate directly into native systemd units, so Podman containers get systemd’s process supervision, dependency ordering, and boot/login integration for free — no separate compose daemon needs to keep running in the background, and it works cleanly rootless.

Can I really run this rootless?

Yes — that’s the point of this setup. Place the unit files in ~/.config/containers/systemd/, run systemctl --user daemon-reload, and use loginctl enable-linger <user> so the services keep running even when you’re logged out. See Usage for the full steps.

FAQ

Mon, 01 Jan 0001 00:00:00 +0000

Why not just use LazyVim or kickstart.nvim?

This config predates/deliberately avoids adopting a distribution. Writing every option, keymap, and plugin spec by hand keeps each piece traceable to a single file instead of hidden behind a distribution’s abstractions and defaults — at the cost of not getting features “for free.” See Introduction for the full reasoning.

Why hand-roll LSP instead of using `nvim-lspconfig`’s `setup{}` presets?

Same reasoning as above, applied specifically to LSP: lua/plugins/lsp.lua calls vim.lsp.start() directly through a small setup_lsp() helper instead of require("lspconfig").<server>.setup{}. It also means the executable-existence guard (vim.fn.executable(...)) is explicit and visible, rather than depending on nvim-lspconfig’s own defaults. See Code Explanation for the code.

Spoljarevic's Knowledgebase

Impressum

Inhalte gemäß § 5 DDG

Kontaktdaten:

Umsatzsteuer-Identifikationsnummer gemäß § 27a UStG:

Redaktionell verantwortlich:

Introduction

What it does

Why it exists

Introduction

What is FreePBX?

Introduction

What is Zammad?

What are Quadlets?

Introduction

What is lazy.nvim?

What this is

Datenschutzerklärung

1. Verantwortlicher

2. Das Wichtigste in Kürze

Usage

Prerequisites

1. Install required Ansible collections

Usage

Prerequisites

1. Clone the repository and build the image

Usage

Prerequisites

1. Configure your environment

Usage

Deployment

First launch

Code Explanation

Repository layout

archPostInstall.yml

Code Explanation

Dockerfile

Code Explanation

Anatomy of a Quadlet unit

Code Explanation

Load order

Plugin spec files

Privacy Policy

1. Controller

2. Summary

FAQ

Can I run this on a different distro?

Do I have to run the entire playbook?

FAQ

Why does the container need privileged: true?

Why isn’t FreePBX installed automatically when I build the image?

FAQ

Why Quadlets instead of docker-compose / podman-compose?

Can I really run this rootless?

FAQ

Why not just use LazyVim or kickstart.nvim?

Why hand-roll LSP instead of using nvim-lspconfig’s setup{} presets?

`archPostInstall.yml`

`Dockerfile`

Why does the container need `privileged: true`?

Why Quadlets instead of `docker-compose` / `podman-compose`?

Why hand-roll LSP instead of using `nvim-lspconfig`’s `setup{}` presets?