<h2>Intro</h2>
<p>I built a small proof of concept to explore how background tasks can be managed in a React app without prop drilling or external state management libraries. The idea was to create a <code>BackgroundTaskProvider</code> that exposes a simple API for starting, pausing, resuming, and cancelling tasks, along with a hook for components to interact with the task system.</p>
<p>The code for the proof of concept is on GitHub: <a href="https://github.com/wardpieters/react-background-task-provider-example">wardpieters/react-background-task-provider-example</a>.</p>
<h2>What the demo does</h2>
<p>The demo keeps task state inside a React context so any component wrapped by the provider can interact with the task system.</p>
<p>Each task tracks a few basic fields:</p>
<ul>
<li><code>progress</code></li>
<li><code>isPaused</code></li>
<li><code>isCompleted</code></li>
<li><code>isError</code></li>
<li><code>isCancelled</code></li>
<li><code>error</code></li>
</ul>
<p>The sample app starts a simulated long-running job that increments progress in steps. While it runs, the UI can pause, resume, or cancel the task, and the current task list is rendered directly from context state.</p>
<h2>Provider design</h2>
<p>The core of the proof of concept is the <code>BackgroundTaskProvider</code> component. It stores the visible task list in React state and also keeps a mutable ref for fast task lookups and updates.</p>
<p>That split is intentional:</p>
<ul>
<li>React state drives re-rendering of the UI.</li>
<li>The ref acts as the source of truth for task control flow inside async task runners.</li>
</ul>
<p>When <code>startTask</code> is called, the provider creates a new task ID, stores an initial status object, and immediately starts the supplied async function. The runner receives a small control API:</p>
<ul>
<li><code>getStatus()</code> to inspect the current task state.</li>
<li><code>setStatus()</code> to update fields like progress.</li>
<li><code>shouldPause()</code> to wait while the task is paused.</li>
<li><code>shouldCancel()</code> to stop execution if the task has been cancelled.</li>
</ul>
<p>That gives the task function enough information to cooperate with the provider without knowing anything about the surrounding UI.</p>
<h2>The hook interface</h2>
<p>The <code>useBackgroundTasks</code> hook is intentionally thin. It just reads the context and throws an error if used outside the provider.</p>
<p>That keeps consumer code simple while still making the dependency explicit. Components either live inside the provider and can control tasks, or they fail fast during development.</p>
<h2>How pause and cancel work</h2>
<p>Pause is cooperative. The runner checks <code>shouldPause()</code> and waits in a short loop until the task is resumed.</p>
<p>Cancel is also cooperative, but stricter. The task checks <code>shouldCancel()</code> and throws if the task has been marked as cancelled or removed.</p>
<p>That approach is enough for a proof of concept because it works cleanly with async JavaScript tasks. It also makes the tradeoff obvious: the task must periodically check in with the provider for cancellation and pause state.</p>
<h3>Why not use workers?</h3>
<p>Both Web Workers and service workers can communicate with the UI in both directions, so in theory pause actions could be sent from React and progress updates could be posted back.</p>
<p>I still chose not to use either one for this prototype. The main goal was to keep progress and control state easy to surface in the UI, and that is simpler when the task stays close to the React tree. Workers add message passing, serialization overhead, and a second state channel to keep in sync, which makes pause, cancel, and incremental progress updates harder to reason about for a small demo like this. Service workers also have a different lifecycle and are aimed at network and caching work, so they are not a natural fit for a UI-driven task runner.</p>
<h2>What I learned</h2>
<p>This prototype confirmed that React context is a reasonable fit for task orchestration when the task lifecycle is mostly UI-driven.</p>
<p>The main benefits are simplicity and discoverability. Any component can start or control a task through the same hook, and the UI can render directly from a shared task list. The provider encapsulates the task logic and state management, so components don't need to worry about the details of how tasks are tracked or updated.</p>
<h2>Conclusion</h2>
<p>The proof of concept showed that a <code>BackgroundTaskProvider</code> plus a <code>useBackgroundTasks</code> hook can form a clean, testable interface for background work in React.</p>
<p>If I turn this into a production feature, the next steps would be better task history and stronger error handling. But as a starting point, the architecture already makes the control flow easy to understand.</p>


Managing background tasks with a React context provider

<h2>Intro</h2>
<p>Keeping system time in sync is important for logs, 2FA, and various time-sensitive applications. In this post I will walk through the exact commands I use to enable NTP synchronization on a Debian system.</p>
<h2>Prerequisites</h2>
<ul>
<li>A Debian-based system</li>
<li>Root or sudo privileges</li>
</ul>
<h2>Install and enable systemd-timesyncd</h2>
<p>Install the systemd-timesyncd package, which provides NTP synchronization functionality:</p>
<pre><code class="language-bash">apt install systemd-timesyncd
</code></pre>
<p>Enable the service to run at boot and start it immediately:</p>
<pre><code class="language-bash">systemctl enable systemd-timesyncd.service --now
</code></pre>
<h2>Enable NTP at the system level</h2>
<p>Tell systemd/timedatectl to use network time synchronization:</p>
<pre><code class="language-bash">timedatectl set-ntp true
</code></pre>
<h2>Verify synchronization</h2>
<p>You can verify if NTP is active with:</p>
<pre><code class="language-bash">timedatectl status
</code></pre>
<p>Look for these lines:</p>
<ul>
<li><code>NTP service: active</code></li>
<li><code>System clock synchronized: yes</code></li>
</ul>
<p>If those values are not active yet, wait a minute and run the status command again.</p>
<h3>Problems?</h3>
<p>If synchronization does not start, first check the service status and logs:</p>
<pre><code class="language-bash">systemctl status systemd-timesyncd.service
journalctl -u systemd-timesyncd.service
</code></pre>
<p>Also verify the system has outbound network access to NTP servers (UDP port 123).</p>


Setting up NTP sync on Debian with systemd-timesyncd

<h2>Intro</h2>
<p>While hosting my own GitLab instance, I noticed one Docker container log had grown to about 55 GiB. That was way too much for a single log file and a good reminder to set log rotation limits.</p>
<p><img src="/images/gitlab-log-usage.png" alt="" loading="lazy"></p>
<p>By default, Docker's <code>json-file</code> log driver can grow indefinitely if you do not configure limits.</p>
<h2>Configure Docker log rotation</h2>
<p>Create or edit <code>/etc/docker/daemon.json</code> and add the following:</p>
<pre><code class="language-json">{
  &quot;log-driver&quot;: &quot;json-file&quot;,
  &quot;log-opts&quot;: {
    &quot;max-size&quot;: &quot;100m&quot;,
    &quot;max-file&quot;: &quot;3&quot;
  }
}
</code></pre>
<p>What this does:</p>
<ul>
<li><code>max-size: 100m</code>: rotate when the log reaches 100 MB.</li>
<li><code>max-file: 3</code>: keep 3 rotated files.</li>
</ul>
<p>So per container, Docker keeps about 300 MB of logs (plus the active file), instead of letting logs grow forever.</p>
<h2>Apply the change</h2>
<p>After updating <code>daemon.json</code>, restart Docker:</p>
<pre><code class="language-bash">sudo systemctl restart docker
</code></pre>
<p>On systems without <code>systemd</code>, use the service manager your distro provides.</p>
<p>Important: this only applies to newly created containers. Existing containers keep their current logging settings.</p>
<p>To apply the new logging options to existing containers, you can recreate them. For example, if you are using <code>docker-compose</code>, you can run:</p>
<pre><code class="language-bash">docker-compose down
docker-compose up -d
</code></pre>
<h2>Conclusion</h2>
<p>If you are running self-hosted services like GitLab, setting Docker log limits is one of those small maintenance tasks that prevents big disk usage surprises later.</p>


Keep Docker container logs from filling your disk

<h2>Intro</h2>
<p>Every now and then I attach an extra virtual disk to a VM. This post documents the full flow I used on a Debian-based VM so future me (and you) can mount a new drive without googling the steps again.</p>
<h2>Prerequisites</h2>
<ul>
<li>You already attached the block device to the VM (in my case it shows up as <code>/dev/sdb</code>).</li>
<li>You have root privileges.</li>
</ul>
<h2>Partition the disk</h2>
<p>Run <code>fdisk</code> against the new device and create a single primary partition that spans the entire disk.</p>
<p>Make sure to replace <code>/dev/sdb</code> with the actual device name of your new disk. You can confirm the device name with <code>lsblk</code> if you're unsure.</p>
<pre><code class="language-bash">fdisk /dev/sdb
</code></pre>
<p>Inside the interactive prompt, press the keys in this order:</p>
<ol>
<li><code>n</code> to create a new partition.</li>
<li><code>p</code> to make it a primary partition.</li>
<li><code>1</code> to accept partition number 1.</li>
<li>Press <code>Enter</code> twice to accept the default first/last sector (fills the disk).</li>
<li><code>w</code> to write the changes and exit.</li>
</ol>
<p>If you rerun <code>fdisk -l /dev/sdb</code> you should now see <code>/dev/sdb1</code> listed.</p>
<h2>Create an ext4 filesystem</h2>
<p>Format the new partition with ext4. This wipes any existing data on <code>/dev/sdb1</code>, so double-check the device path before continuing.</p>
<pre><code class="language-bash">mkfs.ext4 /dev/sdb1
</code></pre>
<h2>Create the mount point</h2>
<p>Pick a descriptive directory name for the mount point so you remember what lives there. I used <code>/mnt/big_data</code>.</p>
<pre><code class="language-bash">mkdir -p /mnt/big_data
</code></pre>
<h2>Add it to /etc/fstab</h2>
<p>To make the mount persistent across reboots, add a line to <code>fstab</code>. I still use <code>nano</code> for quick edits, but use whatever editor you prefer.</p>
<pre><code class="language-bash">nano /etc/fstab
</code></pre>
<p>Append the following line to the bottom of the file:</p>
<pre><code>/dev/sdb1  /mnt/big_data  ext4  defaults  0  2
</code></pre>
<p>Save and exit the editor. This tells <code>mount</code> to treat <code>/dev/sdb1</code> as an ext4 filesystem, mounted at <code>/mnt/big_data</code>, and to perform a non-root filesystem check at boot.</p>
<h2>Reload systemd units and mount everything</h2>
<p>Whenever <code>fstab</code> changes, I run a daemon reload so systemd notices the new mount unit. Then mount all entries to verify the syntax.</p>
<pre><code class="language-bash">systemctl daemon-reload
mount -a
</code></pre>
<p>If <code>mount -a</code> returns silently, the entry is good. To be extra sure, run <code>lsblk</code> and confirm the partition shows the mount point you expect.</p>
<pre><code class="language-bash">lsblk
</code></pre>
<p>At this point the VM automatically mounts <code>/dev/sdb1</code> on <code>/mnt/big_data</code> during boot.</p>
<h3>Problems?</h3>
<p>If you find mistakes or have suggestions, let me know. If you encounter problems, first check that the disk is properly attached and recognized by the OS with <code>lsblk</code>. Then review the <code>fstab</code> entry for typos. You can also check system logs with <code>journalctl -xe</code> for any mount-related errors.</p>


Mounting a fresh data disk on a Linux VM

<h2>Intro</h2>
<p>This post describes the process I went through on how to run a self‑hosted GitLab Runner with the Docker executor and Docker‑in‑Docker to build and push container images.</p>
<p>Below you'll find the relevant parts of my GitLab Runner configuration, and an example <code>.gitlab-ci.yml</code> that builds and pushes images to the registry.</p>
<h2>Prerequisites</h2>
<ul>
<li>A self-hosted GitLab instance.</li>
<li>A virtual machine or server to run the GitLab Runner.</li>
<li>Docker installed on the GitLab Runner host.</li>
<li>Basic knowledge of GitLab CI/CD and Docker.</li>
</ul>
<h2>Setting up a GitLab Runner instance</h2>
<p>To set up a GitLab Runner instance that can build Docker images, use below Docker compose file as a starting point. Adjust the runner token, image, environment variables and other settings to your needs.</p>
<pre><code class="language-yaml">services:
  gitlab-runner:
    image: gitlab/gitlab-runner:latest
    container_name: gitlab-runner
    restart: unless-stopped
    volumes:
      - ./config:/etc/gitlab-runner
      - /var/run/docker.sock:/var/run/docker.sock
</code></pre>
<h2>Configuring the GitLab Runner</h2>
<p>In the <code>config</code> directory, you'll need to create or edit the <code>config.toml</code> file to configure the runner. Below is an example configuration that enables Docker-in-Docker builds.</p>
<p>The key settings here are setting the executor to <code>docker</code>, enabling <code>privileged</code> mode, and adding the <code>/certs/client</code> volume for TLS certificates.</p>
<pre><code class="language-toml">concurrent = 4
check_interval = 0
shutdown_timeout = 0

[session_server]
  session_timeout = 1800

[[runners]]
  name = &quot;gitlab-runner&quot;
  url = &quot;https://git.example.com&quot;
  id = some-runner-id
  token = &quot;some-runner-registration-token&quot;
  token_obtained_at = 2025-11-03T12:30:25Z
  token_expires_at = 0001-01-01T00:00:00Z
  executor = &quot;docker&quot;
  request_concurrency = 4

  [runners.cache]
    MaxUploadedArchiveSize = 0
    [runners.cache.s3]
    [runners.cache.gcs]
    [runners.cache.azure]
  [runners.docker]
    tls_verify = false
    image = &quot;node:latest&quot;
    privileged = true
    disable_entrypoint_overwrite = false
    oom_kill_disable = false
    disable_cache = false

    # https://docs.gitlab.com/ci/docker/using_docker_build#docker-in-docker-with-tls-enabled-in-the-docker-executor
    volumes = [&quot;/certs/client&quot;, &quot;/cache&quot;]
    shm_size = 0
    network_mtu = 0
</code></pre>
<div class="markdown-alert markdown-alert-warning">
<p class="markdown-alert-title">Warning</p>
<p>Setting <code>privileged</code> to <code>true</code> effectively disables the container’s security mechanisms and exposes your host to privilege escalation. This action can cause container breakout. For more information, see <a href="https://docs.docker.com/engine/containers/run/#runtime-privilege-and-linux-capabilities">runtime privilege and Linux capabilities</a>.</p>
</div>
<h2>Example CI/CD configuration</h2>
<p>This CI configiration uses <code>docker:28.5</code> as the image, and <code>docker:28.5-dind</code> as a service. It logs in to the registry, builds the image using buildx, and pushes the image. Adjust tags, cache and build options to taste.</p>
<pre><code class="language-yaml">default:
  image: docker:28.5

variables:
  DOCKER_TLS_CERTDIR: &quot;/certs&quot;

.before-docker:
  - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY

stages:
  - build
  - publish

Build image:
  stage: build
  services:
    - docker:28.5-dind
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  before_script:
    - !reference [.before-docker]
  script:
    - &gt;
      docker buildx build
      --push
      --provenance=false
      --cache-from $CI_REGISTRY_IMAGE:latest
      -f Dockerfile
      -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
      .

Push latest:
  stage: publish
  services:
    - docker:28.5-dind
  variables:
    GIT_STRATEGY: none
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  before_script:
    - !reference [.before-docker]
  script:
    - docker manifest create $CI_REGISTRY_IMAGE:latest $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
    - docker manifest push $CI_REGISTRY_IMAGE:latest
</code></pre>
<h2>Tips and troubleshooting</h2>
<ul>
<li>If jobs fail to connect to the dind service, make sure your GitLab Runner is registered and the runner's Docker daemon supports the dind setup (privileged mode, matching docker versions).</li>
<li>Use <code>DOCKER_TLS_CERTDIR</code> to enable TLS between the client and the dind service and mount the certs via the runner <code>volumes</code> setting.</li>
<li>For faster builds, use build cache (<code>--cache-from</code>) or set up a dedicated cache registry.</li>
<li>If you don't need multi-platform buildx features, you can simplify to <code>docker build --push</code> instead of <code>buildx</code>.</li>
</ul>
<h3>Problems?</h3>
<p>If you find mistakes or have suggestions, let me know. If you encounter problems, check the runner registration, docker versions and <code>privileged</code> settings first.</p>


Setting up GitLab Runner to build Docker images

<p>Running Plex in an unprivileged LXC container on Proxmox 8.4 with Intel Intel Quick Sync Video — or any GPU-accelerated hardware encoding — is a great way to maximize performance of your Plex server. This guide covers updating your kernel, configuring device permissions, and setting up Docker Compose for hardware acceleration.</p>
<h2>1. Update Proxmox Kernel to 6.11</h2>
<p>To ensure the best compatibility and performance with Intel Quick Sync, update your Proxmox host to kernel 6.11:</p>
<pre><code class="language-bash">apt update &amp;&amp; apt dist-upgrade
apt install proxmox-kernel-6.11
reboot
</code></pre>
<p>After rebooting, verify the kernel version:</p>
<pre><code class="language-bash">uname -r
</code></pre>
<p>This should output something like: <code>6.11.x-pve</code>.</p>
<h2>2. Set Device Permissions for GPU Access</h2>
<p>In order to use Intel Quick Sync, the LXC container needs access to the <code>/dev/dri</code> devices. For unprivileged LXC containers, you need to adjust permissions before passing through the device.</p>
<h3>a. Set Kernel Parameter</h3>
<p>Run the following command on the Proxmox host to allow access to performance counters. Add the following line to <code>/etc/sysctl.conf</code> to make this persistent:</p>
<pre><code>kernel.perf_event_paranoid=0
</code></pre>
<p>Then reload sysctl settings:</p>
<pre><code class="language-bash">sysctl -p
</code></pre>
<h3>b. Create a udev Rule for <code>/dev/dri</code></h3>
<p>First, identify your GPU devices. You can do this by running:</p>
<pre><code class="language-bash">ls /dev/dri
</code></pre>
<p>You should see devices like <code>card0</code> and <code>renderD128</code>, which are used as an example in this guide. Create a new udev rule file to set the correct permissions for these devices:</p>
<pre><code class="language-bash">nano /etc/udev/rules.d/99-dri-permissions.rules
</code></pre>
<p>Add the following lines:</p>
<pre><code>KERNEL==&quot;card0&quot;, SUBSYSTEM==&quot;drm&quot;, MODE=&quot;0777&quot;
KERNEL==&quot;renderD128&quot;, SUBSYSTEM==&quot;drm&quot;, MODE=&quot;0777&quot;
</code></pre>
<p>Reload udev rules using below command, or reboot the Proxmox host:</p>
<pre><code class="language-bash">udevadm control --reload-rules &amp;&amp; udevadm trigger
</code></pre>
<h2>3. Pass Through <code>/dev/dri</code> to the LXC Container</h2>
<p>Shut down the LXC container if it is running. Edit your container's config file (e.g., <code>/etc/pve/lxc/100.conf</code>) and add the following lines to the end:</p>
<pre><code>lxc.cgroup2.devices.allow: c 226:0 rwm
lxc.cgroup2.devices.allow: c 226:128 rwm
lxc.cgroup2.devices.allow: c 29:0 rwm
lxc.mount.entry: /dev/dri dev/dri none bind,optional,create=dir
lxc.mount.entry: /dev/dri/card0 dev/dri/card0 none bind,optional,create=file
lxc.mount.entry: /dev/dri/renderD128 dev/renderD128 none bind,optional,create=file
</code></pre>
<p>After editing the config file, start the LXC container again.</p>
<h2>4. Add <code>/dev/dri</code> Mount to Docker Compose</h2>
<p>In your Plex Docker Compose service, add the <code>/dev/dri</code> device to make the GPU available to the Plex container. A full working example is shown at the end of this guide.</p>
<pre><code class="language-yaml">services:
  plex:
    # ...other options...
    devices:
      - /dev/dri:/dev/dri
</code></pre>
<h2>5. Verify Hardware Transcoding in Plex</h2>
<p>Start your Plex container and check if hardware transcoding is enabled. You can do this by going to the Plex dashboard, navigating to Settings &gt; Server &gt; Transcoder, and looking for the &quot;Use hardware acceleration when available&quot; option.</p>
<p>If it is enabled, you should see (hw) next to the transcoder in the dashboard when playing a video that requires transcoding.</p>
<h3>Problems?</h3>
<p>This post has been written with the outmost care, but if you find any mistakes or have any suggestions, please let me know.</p>
<p>If you encounter any problems, check all the steps again and make sure you have followed them correctly.</p>


Setting up Plex in an Unprivileged LXC Container on Proxmox 8.4 with Hardware Encoding

<h2>Intro</h2>
<p>I keep forgetting how to setup manual port forwarding with hairpin NAT, so that's why this post exists.</p>
<h3>Ports/interfaces</h3>
<p>External port: <code>8081</code></p>
<p>Internal IP: <code>192.168.10.197</code><br>
Internal port: <code>8080</code></p>
<p>Note that the internal port is the port that the service is listening on, and the external port is the port that is exposed to the internet.</p>
<p>WAN: <code>pppoe0</code><br>
LAN: <code>switch0.1</code></p>
<p>Replace these details with your own.</p>
<h2>Firewall</h2>
<p>First, we need to create a firewall rule to allow the traffic to reach the destination. This is done by creating a new rule in the <code>WAN_IN</code> (interface <code>pppoe0/in</code>) group.</p>
<p><img src="/images/EdgeRouterX-firewall-port-forward.png" alt="" loading="lazy"><br>
<img src="/images/EdgeRouterX-firewall-port-forward-advanced.png" alt="" loading="lazy"></p>
<p>You can specify a source address or address group to limit the traffic to a specific IP or range of IPs. If you want to allow all traffic, leave this field empty.</p>
<p>Note: you don't have to add your local network range to the source address list, as this isn't a firewall rule for the LAN interface.
<img src="/images/EdgeRouterX-firewall-port-forward-source.png" alt="" loading="lazy"><br>
<img src="/images/EdgeRouterX-firewall-port-forward-destination.png" alt="" loading="lazy"><br>
<img src="/images/EdgeRouterX-firewall-port-forward-overview.png" alt="" loading="lazy"></p>
<h2>DNAT</h2>
<p>Next, we need to create a DNAT rule to forward external traffic to the internal IP and port.</p>
<p><img src="/images/EdgeRouterX-firewall-port-forward-dnat.png" alt="" loading="lazy"></p>
<p>And, another DNAT rule. This time, we need to forward the traffic to the external IP and port.</p>
<p><img src="/images/EdgeRouterX-firewall-port-forward-dnat-local.png" alt="" loading="lazy"></p>
<h2>SNAT</h2>
<p>Finally, to wrap it all up, we need to create an SNAT rule to allow the traffic to return to the client.</p>
<p><img src="/images/EdgeRouterX-firewall-port-forward-snat.png" alt="" loading="lazy"></p>
<h2>Profit!</h2>
<p>That's it! You should now have your port(s) forwarded and accessible from your local network and the internet.</p>
<h3>Problems?</h3>
<p>This post has been written with the outmost care, but if you find any mistakes or have any suggestions, please let me know.</p>
<p>If you encounter any problems, check all the steps again and make sure you have followed them correctly. Setting this up involves multiple steps, so it's important to double-check and ensure that each step is followed correctly.</p>
<h2>Sources</h2>
<p><a href="https://help.ui.com/hc/en-us/articles/204952134-EdgeRouter-Hairpin-NAT">EdgeRouter - Hairpin NAT (help.ui.com)</a><br>
<a href="https://help.ui.com/hc/en-us/articles/205231700-EdgeRouter-Destination-NAT">EdgeRouter - Destination NAT (help.ui.com)</a><br>
<a href="https://help.ui.com/hc/en-us/articles/204976494">EdgeRouter - Source NAT and Masquerade (help.ui.com)</a></p>


EdgeRouter manual port forward with hairpin NAT

<h2>Intro</h2>
<p>GitLab Pages is a great way to host static websites. However, when using a reverse proxy custom domains can be tricky to set up. The GitLab docs describe you need a secondary IP address for this, but this is not always possible.</p>
<p>This guide will show you how to set up GitLab Pages behind a reverse proxy with HTTPS using Caddy and a custom GitLab Pages API written by me (<a href="https://github.com/wardpieters/gitlab-pages-caddy-api">wardpieters/gitlab-pages-caddy-api</a>).</p>
<h2>Steps</h2>
<p>Note: make sure to replace <code>example.com</code> and other example domains with your own domain, and <code>ca@example.com</code> with your own Let's Encrypt contact email address.</p>
<h3>1. Enable GitLab Pages</h3>
<p>Update the values shown below in your <code>gitlab.rb</code> file to enable GitLab Pages, configure the external pages URL and expose the necessary ports locally. Leave everything else as-is.</p>
<h4><code>gitlab.rb</code></h4>
<pre><code class="language-ruby">##! Define to enable GitLab Pages
pages_external_url &quot;https://pages.example.com/&quot;
gitlab_pages['enable'] = true

##! Configure to expose GitLab Pages on external IP address, serving the HTTP
# gitlab_pages['external_http'] = []
gitlab_pages['external_http'] = ['0.0.0.0:8888']
</code></pre>
<pre><code class="language-ruby"># Below you can find settings that are exclusive to &quot;GitLab Pages NGINX&quot;
pages_nginx['enable'] = true
pages_nginx['listen_port'] = 8091
pages_nginx['listen_https'] = false
pages_nginx['redirect_http_to_https'] = true
</code></pre>
<h4><code>docker-compose.yml</code></h4>
<p>Make sure to expose the ports for GitLab Pages and add the local GitLab Pages API using the <code>docker-compose.yml</code> file, only the relevant lines are shown below.</p>
<ul>
<li>Port 8091 is used for the GitLab pages domain (e.g. <code>pages.example.com</code>).</li>
<li>Port 8888 is used for the external domains (e.g. <code>handbook.example.nl</code>).</li>
</ul>
<pre><code class="language-yml">services:
  gitlab-ee:
    ports:
      - &quot;127.0.0.1:8091:8091&quot;
      - &quot;127.0.0.1:8888:8888&quot;
  caddy-api:
    restart: unless-stopped
    image: ghcr.io/wardpieters/gitlab-pages-caddy-api:latest
    ports:
      - &quot;127.0.0.1:8000:5000&quot;
    env_file:
      - .env
</code></pre>
<h4><code>.env</code></h4>
<p>In the same directory as the <code>docker-compose.yml</code> file, create a <code>.env</code> file with the below contents.
Make sure to replace the values with your own. The <code>GITLAB_TOKEN</code> can be created from the GitLab UI and needs to have the <code>api</code> and admin <code>scopes</code>.</p>
<pre><code>GITLAB_TOKEN=xyz
GITLAB_DOMAIN=git.example.com
GITLAB_PAGES_DOMAIN=pages.example.com
</code></pre>
<h3>2. Configure Caddy</h3>
<p>The Caddyfile needs three additions:</p>
<pre><code>{
	on_demand_tls {
		ask http://localhost:8000/api
		interval 2m
		burst 5
	}
}
</code></pre>
<pre><code>:443 {
	tls ca@example.com {
		on_demand
	}

	reverse_proxy http://127.0.0.1:8888 {
		header_down -server
	}
}
</code></pre>
<pre><code>pages.example.com,
*.pages.example.com {
	tls ca@example.com {
		on_demand
	}

	reverse_proxy http://127.0.0.1:8091 {
		header_down -server
	}

	import hsts
}
</code></pre>
<h3>3. Restart</h3>
<p>Restart your GitLab instance and run <code>docker compose up -d</code> to make sure the local GitLab Pages API is running</p>
<h2>Profit!</h2>
<p>That's it! You should now have GitLab Pages running behind a reverse proxy with HTTPS!</p>
<h3>Problems?</h3>
<p>This post has been written with the outmost care, but if you find any mistakes or have any suggestions, please let me know.</p>
<p>If you encounter any problems, check all the steps again and make sure you have followed them correctly. Setting up GitLab Pages involves multiple steps, so it's important to double-check and ensure that each step is followed correctly.</p>


Running GitLab Pages behind a HTTPS reverse proxy

<h2>Intro</h2>
<p>Expo is a great tool for building React Native apps, and GitLab CI/CD is an excellent way to automate the process of building and submitting those apps. In this blog post, we'll walk through the steps necessary to set up a GitLab CI/CD pipeline for building and submitting an Expo React Native app, using semantic-release for versioning and Expo EAS for building and publishing.</p>
<h3>Prerequisites</h3>
<p>A basic understanding of GitLab CI/CD and Expo is assumed. If you are not familiar with these tools, you can learn more about them by reading the <a href="https://docs.gitlab.com/ee/ci/">GitLab CI/CD documentation</a> and the <a href="https://docs.expo.dev/">Expo documentation</a>. In case you are using a self-hosted GitLab instance, you will need to make sure that you have a GitLab Runner installed and configured. For more information on how to do this, see the <a href="https://docs.gitlab.com/runner/">GitLab Runner documentation</a>.</p>
<h2>Setting up semantic-release</h2>
<p>Semantic-release is a tool that automates the process of versioning and releasing code, using commit messages to determine the appropriate version number. To use semantic-release with GitLab CI/CD, we first need to install the necessary packages and configure them appropriately.</p>
<h3>Install semantic-release and plugins</h3>
<p>Use either Yarn or NPM to install the required packages.</p>
<pre><code>yarn add -D semantic-release semantic-release-expo @semantic-release/changelog @semantic-release/commit-analyzer @semantic-release/git @semantic-release/gitlab @semantic-release/npm @semantic-release/release-notes-generator
</code></pre>
<pre><code>npm install --save-dev semantic-release semantic-release-expo @semantic-release/changelog @semantic-release/commit-analyzer @semantic-release/git @semantic-release/gitlab @semantic-release/npm @semantic-release/release-notes-generator
</code></pre>
<p>After installing above packages, we need to make sure the private attribute in the package.json file is set to true. This will prevent the package from being published to the npm registry. Also, set the repository field to the SSH URL of your GitLab repository. You can find this on the GitLab project page under the Clone button.</p>
<pre><code class="language-json">{
  &quot;name&quot;: &quot;my-app&quot;,
  &quot;private&quot;: true,
  &quot;repository&quot;: &quot;git@&lt;YOUR_GITLAB_DOMAIN&gt;:ward/my-app.git&quot;
}
</code></pre>
<h3>Configure semantic-release</h3>
<p>Next, we need to configure semantic-release. We can do this by creating a file called <code>.releaserc.yml</code> in the root of our project. This file will contain the configuration for semantic-release. The configuration below is a good starting point, but you can customize it to your needs. For more information on the configuration options, see the <a href="https://semantic-release.gitbook.io/semantic-release/usage/configuration">semantic-release documentation</a>.</p>
<p>Notice: you should replace <code>YOUR_GITLAB_DOMAIN</code> with your own GitLab domain in the configuration below. Or replace it with <code>gitlab.com</code> if you are using GitLab.com.</p>
<pre><code class="language-yaml">plugins:
  - &quot;@semantic-release/commit-analyzer&quot;
  - &quot;@semantic-release/release-notes-generator&quot;
  - &quot;@semantic-release/npm&quot;
  - - &quot;semantic-release-expo&quot;
    - versions:
        android: &quot;${increment}&quot;
        ios: &quot;${increment}&quot;
  - - &quot;@semantic-release/changelog&quot;
    - changelogFile: CHANGELOG.md
  - - &quot;@semantic-release/git&quot;
    - assets:
        - CHANGELOG.md
        - package.json
        - package-lock.json
        - app.json
      message: &quot;chore(release): ${nextRelease.version}\n\n${nextRelease.notes}&quot;
  - - &quot;@semantic-release/gitlab&quot;
    - gitlabUrl: https://&lt;YOUR_GITLAB_DOMAIN&gt;
</code></pre>
<h2>Setting up GitLab CI/CD</h2>
<p>Now that we have our dependencies and configuration files in place, we can create our GitLab repository and set up our CI/CD pipeline. This involves creating a <code>.gitlab-ci.yml</code> file that specifies the stages of our pipeline (e.g. building the app, publishing the app, etc.) and the commands to run at each stage. We'll also need to set up some environment variables in GitLab to store sensitive information like our Expo credentials.</p>
<h3>Configure GitLab environment variables</h3>
<h4>SSH key</h4>
<p>First, we need to configure the SSH key that will have write access to our GitLab repository. This is necessary for semantic-release to be able to commit the new version to the default branch. To do this, we need to create a new SSH key and add it to our GitLab repository. Use the command below to generate a new SSH key, you can replace <code>my-app</code> with the name of your app or any other name you like.</p>
<p><code>ssh-keygen -f ~/.ssh/my-app -t rsa -b 4096 -C my-app</code></p>
<p>Once the keypair has been generated, copy the contents of the <strong>public</strong> key (e.g. <code>~/.ssh/my-app.pub</code>) and add it to your GitLab Project Deploy Keys by following the instructions <a href="https://docs.gitlab.com/ee/ssh/#deploy-keys">from the GitLab Docs</a>. Make sure the key has write access, as shown in the screenshot below.</p>
<p><img src="/images/GitLab-CI-deploy-key.png" alt="" loading="lazy"></p>
<p>Next, you will need to add the <strong>private</strong> key (e.g. <code>~/.ssh/my-app</code>) to your GitLab Project Environment Variables by following the instructions <a href="https://docs.gitlab.com/ee/ci/variables/index.html#define-a-cicd-variable-in-the-ui">from the GitLab Docs</a>. Make sure the variable name is set to <code>CI_SSH_KEY</code>, as shown in the screenshot below.</p>
<p><img src="/images/GitLab-CI-SSH-key.png" alt="" loading="lazy">
Note: this private key is used for demonstration purposes only and is not in use.</p>
<h4>GitLab token</h4>
<p>The <a href="https://github.com/semantic-release/gitlab"><code>@semantic-release/gitlab</code></a> package requires a GitLab token to be able to create releases. To create a new personal access token, go to your GitLab Preferences and click on Access Tokens. Then fill in the form as shown in the screenshot below and click on 'Create personal access token'.</p>
<p><img src="/images/GitLab-CI-personal-access-token.png" alt="" loading="lazy"></p>
<p>Now, add the token to your GitLab Project Environment Variables by following the instructions <a href="https://docs.gitlab.com/ee/ci/variables/index.html#define-a-cicd-variable-in-the-ui">from the GitLab Docs</a>. Make sure the variable name is set to <code>GL_TOKEN</code>, as shown in the screenshot below.</p>
<p><img src="/images/GitLab-CI-token-variable.png" alt="" loading="lazy"></p>
<h4>Expo credentials</h4>
<p>To build your app with Expo EAS, you will need to add an Expo token to your GitLab Project Environment Variables. You can generate one by going to the Access Tokens section of your Account Settings. As shown on the screenshot below, you will first need to create a Robot user and then generate a new token for that account.</p>
<p><img src="/images/GitLab-CI-Expo-Robot-Token.png" alt="" loading="lazy"></p>
<p>After you have generated the token, add it to your GitLab Project Environment Variables by following the instructions <a href="https://docs.gitlab.com/ee/ci/variables/index.html#define-a-cicd-variable-in-the-ui">from the GitLab Docs</a>. Make sure the variable name is set to <code>EXPO_TOKEN</code>, as shown in the screenshot below.</p>
<p><img src="/images/GitLab-CI-Expo-Robot-Token-variable.png" alt="" loading="lazy"></p>
<p>Now open the <code>app.json</code> file in the root of project and add the <code>owner</code> property, set the value to your Expo username. This is necessary for Expo EAS to be able to build your app.</p>
<pre><code>{
  &quot;expo&quot;: {
    &quot;name&quot;: &quot;my-app&quot;,
    &quot;slug&quot;: &quot;my-app&quot;,
    &quot;owner&quot;: &quot;YOUR_USERNAME&quot;,
    ...
  }
}
</code></pre>
<p>Next, run the <code>eas init</code> and <code>eas build -p all</code> command to initialize your Expo project. You will be asked to provide some information, such as your Apple Developer account details. After completing this, a new project on Expo is created and also a <code>eas.json</code> file in the root of your project. This file contains the configuration for Expo EAS. You can customize this file to your needs, but the default configuration should be fine for most projects.</p>
<h3>Configure GitLab CI/CD pipeline</h3>
<p>In the root of the project, create a file called <code>.gitlab-ci.yml</code>. This file will contain the configuration for our GitLab CI/CD pipeline. The configuration below is a good starting point, but you can customize it to your needs. For more information on the configuration options, see the <a href="https://docs.gitlab.com/ee/ci/yaml/">GitLab CI/CD documentation</a>.</p>
<p>The configuration may seem overwhelming at first, but it is straightforward. The first thing to notice is that we have two stages: test and release. The test stage is used to run tests and other checks on the code and will run on pull requests. The release stage is used to build and publish the app. The release stage is only run when a commit is pushed to the default branch (e.g. master) and the commit author is not <code>semantic-release-bot</code>. This is to prevent the pipeline from running when semantic-release commits a new version to the default branch, and cause an infinite loop.</p>
<pre><code class="language-yaml">stages:
  - test
  - release

before_script:
  - npm install -g expo-cli
  - npm install

node:16:
  image: node:16-alpine
  stage: test
  allow_failure: true
  only:
    - merge_requests
  script:
    - npx tsc
    - expo-cli doctor

bump-version:
  image: node:18-alpine
  stage: release
  rules:
    - if: ($CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH &amp;&amp; $CI_COMMIT_AUTHOR !~ /semantic-release-bot.*/)
  script:
    - &quot;which ssh-agent || ( apk --update add openssh-client git )&quot;
    - mkdir -p ~/.ssh
    - eval $(ssh-agent -s)
    - '[[ -f /.dockerenv ]] &amp;&amp; echo -e &quot;Host *\n\tStrictHostKeyChecking no\n\n&quot; &gt; ~/.ssh/config'
    - ssh-add &lt;(echo &quot;$CI_SSH_KEY&quot;)
    - npx semantic-release

publish:
  image: node:16-alpine
  stage: release
  environment:
    name: production
  only:
    refs:
      - tags
    variables:
      - $CI_COMMIT_TAG =~ /^v.*$/
  before_script:
    - apk --update add git
    - npm install -g expo-cli eas-cli
    - npm install
  script:
    - eas build --platform all --profile production --non-interactive --auto-submit
</code></pre>
<h2>Profit!</h2>
<p>That's it! You can now commit and push your code to GitLab (<code>git add . &amp;&amp; git commit -m &quot;feat(ci): add semantic release&quot; &amp;&amp; git push</code>).</p>
<p>With the GitLab repository and pipelines set up, you are ready to start building and publishing apps automatically. You can simply push code changes to GitLab, and the pipeline will take care of the rest - building the app and publishing it to the appropriate release channel!</p>
<p>You can see the pipeline in action by going to the CI/CD &gt; Pipelines page in your GitLab project.</p>
<p><img src="/images/GitLab-CI-pipelines.png" alt="" loading="lazy"></p>
<h3>Problems?</h3>
<p>This post has been written with the outmost care, but if you find any mistakes or have any suggestions, please let me know.</p>
<p>If you encounter any problems, check all the steps again and make sure you have followed them correctly. Setting up the pipeline involves multiple steps, so it's important to double-check and ensure that each step is followed correctly.</p>


Automating Expo App Builds and Submissions with GitLab CI/CD

<h2>Intro</h2>
<p>This blog post will describe the struggle I went through to set up a Site to Site VPN using two Debian VMs and an EdgeRouter X on both sides of the connection, so you (and future me) don't have to.
The image below describes my network setup. The public IP addresses are not displayed for obvious reasons.</p>
<p><img src="/images/S2S-VPN-diagram.svg" alt="" loading="lazy"></p>
<h2>Port forward</h2>
<p>The WireGuard server (host A) must be reachable from the internet. Therefore you’ll have to port forward UDP port 51825 on Host A (server). The screenshot below shows how to set this up on a EdgeRouter X. Port forwarding is not necessary on host B as this VM acts as a client.</p>
<p><img src="/images/EdgeRouterX-port-forward-WireGuard.png" alt="" loading="lazy"></p>
<h2>VM Setup</h2>
<p>Note: to do this yourself, some knowledge of networking and Linux is required.</p>
<p>To start, I installed Debian 11 running WireGuard on two VMs. The process is basically the same on Ubuntu.</p>
<pre><code class="language-bash">apt-get update
apt-get install -y wireguard iptables
</code></pre>
<p>Before we go any further, we need to edit the <code>/etc/sysctl.conf</code> file on both hosts. Add the line shown below to the file and run <code>sysctl -p</code>.</p>
<pre><code>net.ipv4.ip_forward=1
</code></pre>
<h2>WireGuard Setup</h2>
<p>After setting up the VMs, WireGuard is installed and some commands are now available for us to use. We will use them to generate the public and private key for the config files.
First we will do this on Host A (server):</p>
<pre><code class="language-bash">wg genkey &gt; host-a.key
wg pubkey &lt; host-a.key &gt; host-a.pub
</code></pre>
<p>And then on host B (client):</p>
<pre><code class="language-bash">wg genkey &gt; host-b.key
wg pubkey &lt; host-b.key &gt; host-b.pub
</code></pre>
<p>We will use the contents of the generated files in the WireGuard configuration. On host A (server) we create the file <code>/etc/wireguard/wg0.conf</code> with the content below. Replace the placeholders (e.g. &lt;host-a.key&gt;) with the content of the appropriate files and make sure to replace <code>eth0</code> with your actual network interface.</p>
<pre><code>[Interface]
PrivateKey = &lt;host-a.key&gt;
Address = 10.229.76.1/24
PostUp = iptables -A FORWARD -i %i -j ACCEPT; iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
PostDown = iptables -D FORWARD -i %i -j ACCEPT; iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE
MTU = 1420
ListenPort = 51820
SaveConfig = false

### begin host-b

[Peer]
PublicKey = &lt;host-b.pub&gt;
AllowedIPs = 10.229.76.2/32, 192.168.10.0/24
PersistentKeepalive = 16

### end host-b

</code></pre>
<p>Then we'll create the file <code>/etc/wireguard/wg0.conf</code> on host B (client), but with different content. Make sure to replace <code>eth0</code> with your actual network interface and the <code>Endpoint</code> with the IP address of host A (server).</p>
<pre><code>[Interface]
PrivateKey = &lt;host-b.key&gt;
Address = 10.229.76.2/24
PostUp = iptables -A FORWARD -i %i -j ACCEPT; iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
PostDown = iptables -D FORWARD -i %i -j ACCEPT; iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE

[Peer]
PublicKey = &lt;host-a.pub&gt;
Endpoint = 213.x.x.x:51820
AllowedIPs = 192.168.20.0/24
PersistentKeepalive = 16
</code></pre>
<p>On both hosts we set the WireGuard interface to start on boot and right now by running <code>systemctl enable wg-quick@wg0 --now</code>. If you did everything okay, you should not see any errors.</p>
<h2>Routing</h2>
<p>On the EdgeRouter of both networks you add a static route by clicking on 'Add Static Route' and then entering the information below. On the router of host A add the IP range of host B as destination network and the IP of host A as next hop address. The same goes for the router in the network of host B, but then the other way around.</p>
<p>Note: adjust the IP ranges to your situation!</p>
<p><img src="/images/S2S-VPN-routing.png" alt="" loading="lazy"></p>


Ward Pieters

Recent Blog Posts

Managing background tasks with a React context provider

Setting up NTP sync on Debian with systemd-timesyncd

Keep Docker container logs from filling your disk