DEV Community: Fernando

[Boost]

Fernando — Fri, 11 Apr 2025 14:28:43 +0000

Michael Nikitochkin

Apr 10 '25

Why Infrastructure Engineers Should Start with Backend Development

#programming #infrastructure

Comments

2 min read

Selfhost Timetagger on a Raspberry Pi

Fernando — Mon, 22 Apr 2024 11:00:00 +0000

A few weeks ago I started looking into options for time tracking software. The goal is to be more aware of how I spend my time throughout the day.

I could selfhost something with the Raspberry Pi I have lying around the house

The intrusive thought prevailed, so here's a condensed/quick tutorial of how I made it work

Timetagger

The aarch64 architecture of the Raspberry Pi 4 I wanted to use didn't make this straightforward. I looked for open source projects written in Python for better/easier compatibility.

I chose timetagger.app (github repo) and only a couple days after getting everything running I found the web app quite pleasant to use. I highly recommend it if interested in something like this.

Requirements

Raspberry Pi
- 4 CPU + 8GB RAM runs the project like it's nothing so lower-end versions should also work
- I have a 64bit chip but installed 32bit OS (lite) because packages/tools on 64 bit OS were difficult to work with
A domain with DNS managed on Cloudflare
- Tunnels will allow you access your server publicly with a subdomain

You'll want to have your Raspberry Pi running in your local network. I won't cover the basics here, so I'm assuming you can ssh user@host.local to your device at this point. Read getting started guides if needed.

Run the server

Timetagger has good docs and articules to help you get started with self hosting. Most of what I did I learned it from this article. Rapid fire summary:

Ensure Python & pip are installed
python -m pip install -U timetagger
Create a dir to keep data sudo mkdir /opt/timetagger
Change ownership (to yourself) sudo chown -R [user]: /opt/timetagger/
You can now run the server using python -m timetagger and you'll want to use ENV vars:
- TIMETAGGER_CREDENTIALS=XXXX for username/password hash (generate here)
- TIMETAGGER_LOG_LEVEL=info
- TIMETAGGER_BIND=0.0.0.0:8080
- TIMETAGGER_DATADIR=/opt/timetagger

The web app should now be reachable in your local network on host.local:8080

Cloudflare Tunnels

We want to access the app from anywhere in the world, not just from your WiFi at home.

Kudos to the amazing tutorial from pimylifeup.com which was the source of all I know related to the use of Cloudflare tunnels on a Raspberry Pi. Be sure to check that one out for more details on each step below:

sudo apt update & sudo apt upgrade
sudo apt install curl lsb-release
curl -L https://pkg.cloudflare.com/cloudflare-main.gpg | sudo tee /usr/share/keyrings/cloudflare-archive-keyring.gpg >/dev/null
echo "deb [signed-by=/usr/share/keyrings/cloudflare-archive-keyring.gpg] https://pkg.cloudflare.com/cloudflared $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/cloudflared.list
sudo apt update
sudo apt install cloudflared
cloudflared tunnel login
cloudflared tunnel create TUNNELNAME
cloudflared tunnel route dns TUNNELNAME DOMAINNAME
cloudflared tunnel run --url localhost:8080 TUNNELNAME

I used a subdomain under the fdo.cr domain that I own. You should now be able to reach the web app outside your local network!

systemd services

We want the server + cloudflared to run in the background and start on boot. For this we'll use systemd and luckily cloduflared makes it simple:

Create a config file at ~/.cloudflared/config.yml (example below)
sudo cloudflared --config ~/.cloudflared/config.yml service install
sudo systemctl enable cloudflared
sudo systemctl start cloudflared

tunnel: [TUNNELNAME]
credentials-file: /home/[USERNAME]/.cloudflared/[UUID].json

ingress:
    - hostname: [HOSTNAME]
      service: http://localhost:8080
    - service: http_status:404

We'll do the same for the timetagger server (manual systemd setup). Start by creating /user/local/bin/timetagger_boot.sh (example below). I used a sleep to delay boot and added ENV vars directly, a.k.a. the easiest/laziest solution.

#!/bin/bash

echo "Waiting 5s before startup..."
sleep 5
echo "Starting the server!"
TIMETAGGER_CREDENTIALS=XXXXXXXXXX \
    TIMETAGGER_LOG_LEVEL=info \
    TIMETAGGER_BIND=0.0.0.0:8080 \
    TIMETAGGER_DATADIR=/opt/timetagger \
    python -m timetagger

Now create /etc/systemd/timetagger.service (example below). Notice this example is using your user to run the service (not root).

[Unit]
Description=Timetagger service
After=network.target
StartLimitIntervalSec=0

[Service]
Type=simple
ExecStart=timetagger_boot.sh
Restart=always
RestartSec=30
User=[USERNAME]

[Install]
WantedBy=multi-user.target

Finally systemctl daemon-reload or sudo reboot to ensure the services are available on your public subdomain.

Performance

Browsing the app (relatively aggressively) while looking in htop shows 0.12 on load average which is basically nothing. I ran a quick benchmark with ab -n 10000 -c 10 https://[SUBDOMAIN].fdo.cr/timetagger/app/demo and saw these results:

Document Path:          /timetagger/app/demo
Document Length:        11559 bytes

Concurrency Level:      10
Time taken for tests:   200.090 seconds
Complete requests:      10000
Failed requests:        7
   (Connect: 0, Receive: 0, Length: 7, Exceptions: 0)
Total transferred:      121439275 bytes
HTML transferred:       115516711 bytes
Requests per second:    49.98 [#/sec] (mean)
Time per request:       200.090 [ms] (mean)
Time per request:       20.009 [ms] (mean, across all concurrent requests)
Transfer rate:          592.70 [Kbytes/sec] received

Connection Times (ms)
              min  mean[+/-sd] median   max
Connect:        0  112  56.5     97    1169
Processing:    44   87  38.4     79    1228
Waiting:       41   82  35.8     74    1227
Total:        109  200  69.7    180    1459

Percentage of the requests served within a certain time (ms)
  50%    180
  66%    196
  75%    212
  80%    225
  90%    278
  95%    329
  98%    402
  99%    458
 100%   1459 (longest request)

There are lots of caveats to note, i.e. the fact 10 concurrent users is 10x what this server will ever face, it doesn't resemble real user behavior and follow up requests come in immediately one after the other.

Regardless of the caveats, a few of the noteworthy stats from the results:

The test transferred a total of 115 MB of HTML in 200s (~0.57 MB per second)
Requests had a mean time of 200ms and a P95 of 329ms
Load averge on htop barely went over 1 (out of 4 CPUs on the device)

Considering it's running SQLite and the Python server connected publicly with a Cloudflare Tunnel (CPU hungry process) I can say the Raspberry Pi is impressively powerful.

Conclusion

A $35-ish home server vs what a subscription service could cost per year

I find that ^ comparison an interesting one. Proprietary SaaS offerings have delightful UI/UX and lots of extra integrations/tools, but could cost $50 or $100+ per year. Timetagger itself notably sells a lifetime plan for €144 which I would consider if I were to stop selfhosting.

I saw generous Free tiers but they wipe out your historic data or have some other way to hook you into subscribing. No hate intended, it's business strategy.

For my needs, the OSS project I can run on my server at home will be my preferred choice.

A $35-ish home server vs $5-ish/month VPS

This ^ other comparison is easily won by the Raspberry Pi home server. $60/year will get you 1 CPU (shared), 1-2GB RAM and limited SSD on a cloud provider. A Raspberry Pi has 4x those specs with large SD card storage limits if needed (30GB are plenty and cheap though).

You would benefit from the uptime and high bandwith + low latency connection of a datacenter when compared to your house WiFi, but that's about it. For a hobby project this will be perfect.

Kudos to all the people working on OSS (and writing about it) that made this weird weekend project a reality. Also, hats off if you've made it this far reading and/or are willing to try this out for yourself. Pura Vida!

Keeping up with my cat's 💩 using a RaspberryPi

Fernando — Tue, 23 May 2023 18:08:11 +0000

As a former dog owner and first time cat dad I was amazed at how cats are "potty trained" practically from birth. I was prepared to deal with the smell when having to clean the litter box. However, I didn't expect their bowel movements (💩) to carry a punch that would stink up half my apartment.

This might not be the case for everyone, but certainly for me, with an indoor cat in a 2 bedroom apartment without a naturally ventilated place to keep her litter box.

The hero/villain of the story

Her name is Dua and she is a cuddly & playful rescue tortie cat. Dua loves to play with her mouse toys and adores wet food, the latter of which is likely the reason I'm writing this post 😵‍💫

I have her litter box in my second bathroom's shower. The bathroom has an extractor fan that runs when the bathroom light is on, but she ~~refuses to~~ hasn't figured out how to turn it on and off each time she goes #2... Annoying, right?

Automating the extractor fan

To mitigate the smell I wanted the lights to turn on when Dua goes in her litter box. To do this I put together a few things:

RaspberryPi Zero W
- WiFi support was the goal
PIR motion sensor
- Placed on the bathroom wall with "velcro stickers"
Smart switch for bathroom lights (any brand will do) paired with an Alexa
Voicemonkey webhook to trigger an Alexa routine
- "Alexa, turn on the switch for 5 minutes"

The software that calls the webhook (which in turn triggers the Alexa routine) can be found here:

fdocr / pir_trigger

Script that connects a PIR Sensor to a webhook

PIR Trigger

Script that connects a PIR Sensor to a webhook.

Usage

Clone the repo in a folder, install dependencies and then run in background

# Install requirements
pip install -r requirements.txt

# Run in background
# TODO: Find/Document a better way to do this
TRIGGER_URL="<webhook_url>" python main.py &

Otherwise add TRIGGER_URL = "<webhook_url>" to an .env file and the script will pick it up.

The script writes its own PID to pid.txt so it can be used. Examples:

# Follow output of background process
tail -f /proc/$(cat pid.txt)/fd/1

# Kill process
kill -9 $(cat pid.txt)

Sensor to board connections

Cable diagram here

The script was inspired by this Raspberry Pi Foundation article and uses their suggested example layout. The sensor needs 5v (Vcc) and Ground (Gnd), so PIN 2 and PIN 6 work well. Connect the sensor's output (Out) to…

View on GitHub

It works!

Here's what the hardware looks like in action

RPi and motion sensor

Awful quality GIF of our hero/villain

💩 Stats

With all of this in place I went a step further and added Opentelemetry to track the stats of how often the routine was being triggered on Honeycomb.

I wanted to know if I was turning on the bathroom lights over false positives from the motion sensor, but after some tests it simply serves the purpose of telling how often she goes in her litter box.

Last 7 days 💩 activity

Last 24 hours 💩 activity

Interestingly, I can tell she goes in her litter box (# of motion sensor triggers) on average ~8.5 times per day. I don't think many cat owners can say they know this about their feline friends. I do remember and took inspiration from Aaron Patterson doing something similar a long time ago though.

Anyways, that's it. Pura vida!

Background jobs for Kemal server in Crystal lang

Fernando — Thu, 02 Mar 2023 12:00:00 +0000

Yet another post about the Battlesnake project I've been working on while diving in Crystal lang.

This is a quick continuation of yesterday's post about storing data in a DB. I mentioned why I took a performance hit and the solution implemented was to persist the data to DB from a background job. The idea is that enqueuing the jobs to Redis would ideally perform better than waiting for a DB write.

Again, FYI the code is on GitHub.

Mosquito

The Crytal Sidekiq port was a tempting option for a background task runner, but I went with mosquito-cr/mosquito. My initializer looks like this:

require "mosquito"

Mosquito.configure do |settings|
  settings.redis_url = (ENV["REDIS_URL"]? || "redis://localhost:6379")
end

Since initializers are required by src/app.cr (more about this on a previous post) I can now enqueue the job where I once persisted directly to DB. Snippets from all of this below:

# Replaces `Turn.create(...)`
PersistTurnJob.new(
  path: env.request.path,
  context_json: env.params.json.to_json
).enqueue

# src/jobs/persist_turn_job.cr

require "mosquito"

class PersistTurnJob < ApplicationJob
  params(path : String, context_json : String)

  def trace_perform
    context = BattleSnake::Context.from_json(context_json)
    dead = context.board.snakes.find { |s| s.id == context.you.id }.nil?
    turn = Turn.create(
      game_id: context.game.id,
      snake_id: context.you.id,
      context: context_json,
      path: path,
      dead: dead
    )
  end
end

In order to have OpenTelemetry tracing of the jobs I inherit from my ApplicationJob.

# src/jobs/application_job.cr

require "mosquito"

# Base class for jobs in the app. Overrides `perform` so that jobs can
# implement `trace_perform` instead. This will allow for OpenTelemetry tracing
# if available, otherwise the job will be executed as it would if it overrides
# `perform` (mosquito standard). If someone does override `perform` on the job
# it will also have no behavior effect, other than tracing not taking place.
abstract class ApplicationJob < Mosquito::QueuedJob
  def perform
    if ENV["HONEYCOMB_API_KEY"]?.presence
      OpenTelemetry.trace self.class.to_s do |span|
        span.kind = :internal
        trace_perform
      end
    else
      trace_perform
    end
  end
end

Worker

Until now the app produced only one executable, which was the API server. The worker that runs these background jobs is src/worker.cr file and looks like this:

require "./battle_snake/**"
require "./strategy/**"

require "dotenv"
Dotenv.load if File.exists?(".env")
require "./initializers/**"
require "./models/**"
require "./jobs/**"

Mosquito::Runner.start

It requires all dependencies and starts the mosquito runner, but how to work on it locally?

I have a sam.cr task in place that helps me with local develpment. I tweaked make sam dev to spin up two Sentry runners, and it continues to work seamlessly with both development executables + livereload (livecompile?) again.

Dockerfile

I use a Docker deployment on DigitalOcean's App Platform (previous post about this), so I need to change the Dockerfile so that both executables are compiled & included there. This allows to execute either one from the same image passing in the command to override the default ENTRYPOINT (reference).

It now looks like this:

# Build image
FROM crystallang/crystal:1.7.2-alpine as builder
WORKDIR /opt
# Cache dependencies
COPY ./shard.yml ./shard.lock /opt/
RUN shards install -v
# Build a binary
COPY . /opt/
RUN crystal build --static --release ./src/app.cr
RUN crystal build --static --release ./src/worker.cr
RUN crystal build --static --release ./src/money_hack.cr
# ===============
# Result image with one layer
FROM alpine:latest
WORKDIR /
COPY --from=builder /opt/app .
COPY --from=builder /opt/worker .
COPY --from=builder /opt/money_hack .
ENTRYPOINT ["./money_hack"]

It's now compiling src/app.cr, src/worker.cr, and... src/money_hack.cr? Well, I already mentioned I'm not trying to spend more money than needed on this project.

My solution was to run both the server and the worker on the same node/droplet. There are many disadvantages to this so I don't recommend this practice as a rule of thumb (hence the name src/money_hack.cr). Managing this with Kemal/Mosquito configs or independent horizontal scaling as needed are likely better solutions.

#! /usr/bin/env crystal
#
# Runs both the server and worker executables in separate fibers to avoid
# independent deployments. Motivation is saving costs
#

channel = Channel(Nil).new

spawns = ["./app -p 8080", "./worker"].map do |command|
  spawn do
    res = system command
    channel.send(nil) unless res
  end
end

channel.receive

Resource consumption & performance

First of all, there's now two executables running on the same droplet that used to only run the API server. These are the insights of the small instance running 512 MB RAM | 1 vCPU x 1 (last 7 days).

I marked in red the (approximate) regions to explain them better.

Region	Memory average	CPU average	Notes
1	13%	0%-1%	Pre-data persistance (no DB)
2	variable	variable	development (debug/errors/deployments)
3	13%	1%-2%	sync DB persistance (prev post)
4	variable	variable	development (debug/errors/deployments)
5	16%	1%-2%	Background job persistance

In region 1 there's ~13% memory usage and that remains unchanged during region 3. With the worker processing jobs region 4 did consume ~16% memory, which is very little difference IMO. CPU usage in region 1 was 0% and 1% at times (5min granularity). With both persitance implementations on region 3 and 5 it bumped up to 1% and 2% values.

All of this tells me that we could (in theory) refactor money_hack.cr to have many workers in parallel before getting close to maxing out the hardware capabilities. Definitely not necessary for now, specially since the bottleneck is DB/Redis hardware. Just a funny situation to think about.

Telemetry comparison

The COUNT, P50, P95, and P99 of traces across the last few days below

BEFORE DB PERSISTANCE

SYNC DB PERSISTANCE

ASYNC WORKER DB PERSISTANCE

That's great! ~2x better in P50, ~2.5x better in P95, and ~5x better in P99. Nothing compares to raw Crystal code execution with sub-millisecond response times, but this isn't bad in any way considering we have everything integrated in the project.

Below is the telemetry on the job execution too. An alternative would be aggregating/querying logs I guess, but with the existing integration it's an easy way to measure them too.

It makes sense to see the jobs perform similar to the sync DB persistance telemetry data. Reassures the assumption (widely known/used approach) that DB requests are slower than Redis in this scenario.

Conclusions

The app is starting to look sturdy to me, as in there are a few moving pieces now and it performs nicely (fast and reliable). It's also a joy to work with Crystal code.

I have one more post in mind for the series, at least for a while, so I'm excited about sharing that sometime soon.

Pura vida.

Database for Kemal server in Crystal lang

Fernando — Wed, 01 Mar 2023 13:00:00 +0000

This is another post about the Battlesnake project I've been working on while diving in Crystal lang.

This time I'm looking into persisting the game data to a database for analysis. This will allow me to review games from each game played by the bot and hopefully improve my spot on the leaderboards by tweaking my strategy.

FYI the code is on GitHub.

Jennifer.cr

imdrasil/jennifer.cr is my ORM of choice, but I'm no longer following the recommended config directory in the root of the project. I'm just stuffing initializers to be required from the main app files (i.e. src/app.cr).

This is what the database initializer can look like:

# src/initializers/database.cr

require "kemal"
require "jennifer"
require "jennifer/adapter/postgres"

Jennifer::Config.configure do |conf|
  conf.from_uri(ENV["DATABASE_URL"]) if ENV.has_key?("DATABASE_URL")
  conf.logger.level = Log::Severity::Debug
  conf.adapter = "postgres"
  conf.pool_size = (ENV["DB_POOL"] ||= "5").to_i
end

Jennifer docs are great. I found a couple of difficulties along the way, mostly related to configuration details, but made it work with help from kind folks on GitHub (shoutout to @seesethcode).

Migration & Model

It's not quite like ActiveRecord (maybe nothing is/will be 😅), but IMO it's great and has lots of incredibly valuable features (i.e. built in migration management, query dsl, etc). Here's what the migration and model look like:

class CreateTurns < Jennifer::Migration::Base
  def up
    create_table :turns do |t|
      t.string :game_id, {:null => false}
      t.string :snake_id, {:null => false}
      t.text :context, {:null => false}
      t.string :path, {:null => false}
      t.bool :dead, {:null => false, :default => false}

      t.index :game_id
      t.index :path

      t.timestamps
    end
  end

  def down
    drop_table :turns if table_exists? :turns
  end
end

# This is a DB record representation of a request from a game for either
# start/move/end request.
# 
# NOTE: https://imdrasil.github.io/jennifer.cr/docs/model_mapping
class Turn < Jennifer::Model::Base
  with_timestamps

  mapping(
    id: Primary64,
    game_id: String,
    snake_id: String,
    context: String,
    path: String,
    dead: Bool,
    created_at: Time?,
    updated_at: Time?,
  )
end

With all of this in place I added this macro to src/app.cr and called it from within /start, /move, /end endpoints so the turn data gets persisted in Postgres.

macro persist_turn!
  dead = context.board.snakes.find { |s| s.id == context.you.id }.nil?
  Turn.create(
    game_id: context.game.id,
    snake_id: context.you.id,
    context: env.params.json.to_json,
    path: env.request.path,
    dead: dead
  )
end

I left this run through Monday's leaderboard matches and it worked. You can check out the most recent games persisted by my snake in https://snake.fdo.cr/games

Performance impact

Now that we're storing (inserting) data to PostgreSQL, which is currently hosted in a low cost server, response times should've slowed down a noticeable amount.

OpenTelemetry data on Honeycomb is able to tell me exactly how it performed (read my post about this here).

BEFORE

AFTER

There's indeed a penalty in persisting data, likely coming from network latency and the low cost DB server performance being much lower than ideal... I'm saving $$ with that pet (as in "not caddle") server (droplet on DO) hosting Redis+Postgres maintained by me. This hack saves me ~$25/month and could merit a post in and of itself 😆

Anyways, Battlesnake rules usually work with a 500ms timeout, which means we have time to spare for now.

How to recover/regain performance

I'm not going to start spending money on high performing tiers of hosted Postgres services anytime soon, so I could think of ways to avoid such a costly penatly. One option is to store the Turn data asynchronously.

Redis is better performing than Postgres, so queuing the data to be persisted to DB by a background job instead of synchronously when the request is made might help improve response times again.

I actually already have this implemented with the mosquito shard, but that will be covered in the next post of this series. I'm waiting for at least a day's worth of leaderboard match data to reliably compare with the results above, so stay tuned if interested I guess.

Pura vida.

Algorithms and standard library modules in my Battlesnake

Fernando — Thu, 23 Feb 2023 12:00:00 +0000

The first post in the series walked through the code of my current strategy. This one will share a few of the learnings from writing the utility algorithms in the project (as examples for) where I used Crystal's standard library modules.

Parsing JSON in Crystal

This is a common task that has to be dealt with on every language. Crystal provides the JSON::Serializable module for you to include in your class. That way you get to_json and from_json methods based on properties & annotations. The module's usage instructions (docs) are great.

It might be cumbersome to work through a nested object hierarchy when first setting it up, but it's pretty neat to parse Battlesnake's context and then work with all objects (i.e. @context.board.snakes.head, @context.board.width, etc). Pretty neat to have instant feedback against typos when working with these thanks to the compiler thereafter too.

The classes in the /src/battle_snake directory are the representation of the game that comes in as JSON payload on each turn.

A* Search Algorithm

a_star.cr is the utility method (docs reference) that will find the shortest path from a point A to a point B. In this context, a point is a BattleSnake::Point that represents a coordinate (x, y) on the board.

The history and how it works is explained in wikipedia. My implementation is on GitHub (here).

I'm sure there are potential optimizations, but I did my best to make it efficient with things like using the recommended priority queue data structure with spider-gazelle/priority-queue. After all the server needs to respond quick (<500ms) for it to play the game and we need to trust we can call utility methods many times on a single turn to make a decision.

Comparing points (distance)

In order to compare and sort custom classes on data structures Crystal provides the Comparable module/mixin. The formula to know the distance between two BattleSnake::Point looks like this (class code here):

def <=>(other : Point)
  (x - other.x).abs + (y - other.y).abs
end

Known as Manhattan distance and by a few other names, this is the basis of how we can tell how far away two points are from each other. This is key in being able to implement A* on a board, which could be thought of as a graph with equal distance (1) from each node.

Now our class automatically gets the conventional comparison operators (<, <=, ==, >=, and >) populated based off it and data structures like arrays can sort them too.

Flood fill

This is an algorithm that determines all the possible area that can be reached, as oppossed to what all the empty points on the board because a section might be blocked off and unreachable (docs reference).

My own (summarized) way of explaining it would be "an iterative processing of all valid nearby spaces".

More about flood fill on wikipedia. My implementation is on GitHub (here).

This comes in handy when making a decision between different valid moves on a strategy. Consider if you had to choose bewteen (a) move to the right and end up with a flood fill area of 3, or (b) move to the left and end up with a flood fill area of 12. Option (a) sounds like the best one.

That's how CautiousCarol decides to take a left instead of running into an enclosed area (dead end): By calculating what those flood fill results are and picking the largest one.

Conclusions

There are other modules/mixins that can be included or used to extend classes (i.e. Enumerable), so these are just two situations applied to this specific project.

I had flashbacks to university memories when working on these. Nostalgic and fun. The cool thing is that now every new strategy I can work on will be able to use any of these if need be.

Kudos to the BattleSnake team for the resources they upload, like the Deep Learning: Useful Battlesnake Algorithms
YouTube video, where I learned a lot about how these and other algorithms can be applied in BattleSnake.

Pura vida.

Documenting a Crystal open source project

Fernando — Tue, 21 Feb 2023 12:00:00 +0000

This post is a quick overview of how Crystal lang built-in documentation features work and an easy setup to host them for free for Open Source projects. A compilation of things I've seen across Crystal repos and applied on mine.

Documenting code

Crystal maintains a crystal docs command that processes your project's codebase and exports a website with the README & inline comments. IMO it's awesome to encourage documentation to live within the codebase itself.

The generated site will reference/link files (i.e. Module::Class mentions are automatically resolved and converted into links to the respective feature), Admonitions (i.e. support for NOTE, TODO, etc notes), Inheriting Documentation (based on class inheritance), amongst others.

Official Crystal documenting code guide

GitHub Actions ➡ GitHub Pages

Automating becomes possible when putting GitHub actions & pages together, something I jumped into as soon as I realized it would be cool to ensure the docs are always up-to-date with the main branch. Here's what my docs.yml GitHub action looks like:

name: Upload docs
on:
  push:
    branches: [main]
permissions:
  contents: write
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout 🛎️
        uses: actions/checkout@v3

      - name: Install Crystal
        uses: crystal-lang/install-crystal@v1

      - name: Build docs
        run: shards && crystal docs

      - name: Deploy 🚀
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          folder: docs # The folder the action should deploy.

The docs are generated and committed to gh-pages branch, so once enabled in the repo's settings (screenshot below) you'll get https://<username>.github.io/<repo-name> website hosted (for free).

I didn't enable a custom domain because I'm okay with GitHub's subdomain, but that should be able to work out with the proper DNS configuration (tutorial) if you rather have the site hosted on a subdomain of yours.

What it looks like

The landing pages will be the README, and you can structure that however you prefer. This is what the current README of the battlesnake project looks like compared to the hosted site.

It's great to be able to dive deeper into each model class (i.e. BattleSnake::Context) or an existing Strategy (i.e. Strategy::CautiousCarol) from the README references or the navigation on the left side.

A small problem I noticed is that markdown tables (from README) aren't supported yet. I still find this documentation hosting awesome for either when the repo is a shard (for others to reference), or when you/team need to keep up docs (context) for reference on the project down the road.

Pura vida.

Deploy a Crystal app with Docker and Opentelemetry

Fernando — Wed, 15 Feb 2023 12:30:00 +0000

This is the continuation of the previous post in this series about a Battlesnake server.

Learning Crystal with Battlesnake

Fernando ・ Feb 14 '23

#crystal #opensource #api

This one will talk about what the deploy process looks like and some Opentelemetry data collected from it.

Digitalocean App Platform with Dockerfile

I've been a Digitalocean customer/user for a while now so I gave their App Platform PaaS a try. They use buildpacks or detect a Dockerfile which will build and run your app, and I went with the latter (not sure if the Crystal buildpack is supported somewhow).

Michael Nikitochkin's article taught me ~95% of what I needed to come up with an efficient container deployment with a small footprint image (alpine).

# Build image
FROM crystallang/crystal:1.7.2-alpine as builder
WORKDIR /opt
# Cache dependencies
COPY ./shard.yml ./shard.lock /opt/
RUN shards install -v
# Build a binary
COPY . /opt/
RUN crystal build --static --release ./src/app.cr
# ===============
# Result image with one layer
FROM alpine:latest
WORKDIR /
COPY --from=builder /opt/app .
ENTRYPOINT ["./app", "-p", "8080"]

The app is deployed with every commit to main and cached layers are nice. The entire process takes ~2min40s on average when a docker image needs to be built (with cached dependencies) and when the deploy was triggered by a config update (i.e. ENV variable update) it takes under 2min on averge.

Opentelemetry

To understand what's going on I added Opentelemetry tracing with Honeycomb.io. Some cool stats from a few days of ranking on the leaderboards:

You can tell leaderboards run on specific hours and the server sits there without much activity about half the time. My favorite stat there is P99 on ~3.1 milliseconds with all that logic running (from previous post).

Lots of responses manage to respond in microseconds though, as seen in the runtime logs (below) and the P50 stat on Honeycomb (above):

All in all pretty sweet ⚡️

More about other learnings from this project to come soon.

Pura vida.

Learning Crystal with Battlesnake

Fernando — Tue, 14 Feb 2023 16:47:32 +0000

Recently I've been interested in Crystal lang so I worked on a Battlesnake implementation to get more practice under my belt. I'm sharing an overview of it in this post and the code is open source on GitHub.

Battlesnake is a multiplayer game where a small server you write plays a survival-style snake game paired with snakes implemented by others.

The app

I'm using Kemal for framework. The simplicity (Ruby/Sinatra similarity) won me over when paired with Crystal performance. This is what the entire Battlenake API implementation looks like at the time of this writing:

get "/" do
  {
    "apiversion": "1",
    "author": "fdocr",
    "color": ENV["SNAKE_COLOR"] ||= "#e3dada",
    "head": ENV["SNAKE_HEAD"] ||= "default",
    "tail": ENV["SNAKE_TAIL"] ||= "default",
    "version": \{\{ `shards version "#{__DIR__}"`.chomp.stringify \}\}
  }.to_json
end

post "/start" do |env|
  context = BattleSnake::Context.from_json(env.params.json.to_json)
end

post "/move" do |env|
  context = BattleSnake::Context.from_json(env.params.json.to_json)

  case ENV["STRATEGY"] ||= "RandomValid"
  when "RandomValid"
    move = Strategy::RandomValid.new(context).move
  when "ChaseClosestFood"
    move = Strategy::ChaseClosestFood.new(context).move
  when "ChaseRandomFood"
    move = Strategy::ChaseRandomFood.new(context).move
  when "CautiousCarol"
    move = Strategy::CautiousCarol.new(context).move
  else
    move = Strategy::RandomValid.new(context).move
  end

  res = { "move": move, "shout": "Moving #{move}!" }
  res.to_json
end

post "/end" do |env|
  context = BattleSnake::Context.from_json(env.params.json.to_json)
end

Quite Ruby-like so I hope it's easy to follow along whether you've written Crystal before or not.

/start + /end aren't actually doing anything other than parsing the payload provided and / responds with the snake's skin customizations. /move picks from the existing strategies to respond based on an ENV variable.

The devil is in the details since the bulk of the logic lives in the models (parse game context from request payload, house a few utility methods, etc), strategies to respond with a move and utility algorithms. They all feel easy to follow along though.

IMO notes/thoughts so far:

I haven't felt the need to work with macros yet so it's been very similar to a Ruby project.

Reworking data structures on the fly (while working/re-working strategies) took some new time/energy to get right compared to Ruby. There's been close to 0 debugging time related to exceptions I would've likely had to catch when putting together a Ruby script because of the compiler (maybe? likely?).

I have a clunky env.params.json.to_json up there that bothers me a bit. I think that could be cleaned up by figuring out the way to get the raw (String) payload instead of the Kemal parsed (Hash/Object) parameter though. That's a TODO for now.

Strategies & Algorithms implemented

Since Crystal is object oriented I created an abstract/virtual class that all strategies inherit from.

RandomValid considers all the valid moves for your snake on the current context and picks one at random
- Takes into account walls and other snakes' current position
ChaseClosestFood and ChaseRandomFood both aim towards food on the board and differ in how they pick their target (Closest vs Random)
- They re-use RandomValid in some scenarios (i.e. can't reach food)
- They use A* search algorithm to find the best route towards a target (food in this case but can be used on any Point on the board)

The re-usability of strategies makes for a cool way to mix & match them, meaning I can build on top of each other or existing algorithms. The food chaser ones won all the challenges (not sure if challenges are still a thing after the recent UI revamp) so that started to show some potential.

CautiousCarol is a heuristic strategy I implemented and looks like this:

# Strategy that chases the closest available food from the board with caution
# against head-to-head collisions. When a potentially dangerous move is in the
# way it analyzes the other valid moves available and picks the one with the 
# most open area of the board to avoid enclosed spaces.
class Strategy::CautiousCarol < Strategy::Base
  def move
    valid_moves = @context.valid_moves(@context.you.head)
    return RandomValid.new(@context).move if valid_moves[:moves].empty?

    # Check for head-to-head collision possibilities
    dangerous_moves = [] of BattleSnake::Point
    enemies = @context.board.snakes.reject { |s| s.id == @context.you.id }
    enemies.each do |snake|
      next if snake.head <=> @context.you.head > 2
      next if snake.body.size < @context.you.body.size

      # Check if we share valid moves (meeting point for collision)
      @context.valid_moves(snake.head)[:neighbors].values.each do |point|
        meeting_point = valid_moves[:neighbors].values.find do |p|
          (point <=> p).zero?
        end
        next if meeting_point.nil?
        dangerous_moves << point
      end
    end

    # Attempt to chase closest food unless dangerous move is detected
    closest_food = ChaseClosestFood.new(@context).move
    target_point = @context.you.head.move(closest_food)
    safe_move = dangerous_moves.find { |p| (p <=> target_point).zero? }.nil?
    return closest_food if safe_move

    # Leftover valid moves (not chasing closest food anymore) & fallback to
    # RandomValid if no other moves are available (likely run into own death)
    safe_moves = valid_moves[:moves].reject { |move| move == closest_food }
    return RandomValid.new(@context).move if safe_moves.size.zero?

    # Use flood fill to pick the valid move with more space to spare as an 
    # attempt to avoid small areas
    flood_fills = {} of Int32 => String
    contexts = [] of BattleSnake::Context
    safe_moves.size.times { contexts << @context.dup }
    safe_moves.each_with_index do |move, i|
      contexts[i].move(@context.you.id, move)
      area_size = Utils.flood_fill(@context.you.head, contexts[i]).size
      flood_fills[area_size] = move
    end

    # Pick the direction with the largest available area
    flood_fills[flood_fills.keys.sort.last]
  end
end

That's likely a lot to take in, but if interested in comparing it to Ruby or other languages give it a try and ask me about it. I'm not that experienced in Crystal so there are likely details that could improve this.

Overall there's model manipulation (i.e. using the snakes from the board of the current context), utility method usage from the models (i.e. calls to @context.valid_moves), reusing of RandomValid & ChaseClosestFood strategies, and Utils.flood_fill, which is my implementation of Flood Fill algorithm.

My first version of this strategy was a clunky attempt to brute-force a "look ahead" simulation of all possible scenarios. I scrapped that idea in favor of the above for now.

Leaderboard results

That first version of CautiosCarol performed "alright". I was surprised it earned points and ranked on the board overall since I knew it wasn't great. After a couple of days on the Standard leaderboard (4 players on 11x11 board) it ranked like this out of ~100 snakes.

After the fix with the code above on CautiousCarol and another couple of days on the same leaderboard I saw some improvement:

I also realized that same snake could rank on the Duels leaderboard too (1v1 on 11x11 board). Apparently CautiousCarol performs better there (in ranking position but fewer points so I'm not sure how much better really 😅)

Conclusions

Crystal has felt easy to read and write for me, quite nice to use overall and very similar to Ruby in lots of ways (specially at this level without diving into macros). The project is open source on GitHub if interested in checking it out.

I hope this is the first of a few posts on other specific Crystal learnings I had while experimenting here. Also might update if I come up with new/better strategies.

Pura vida.

Using Chart.js plugins with webpack

Fernando — Sun, 03 Jul 2022 12:57:02 +0000

This post shares the steps I took to include Chart.js with candlestick charts (using a plugin) on my weekend/pet project. I'm using webpack to bundle its JavaScript code & dependencies.

I'm trying to write this in a framework agnostic way, but the fact is I'm using webpack in a Ruby on Rails app (via jsbundling-rails), so there will be some specifics that may differ from someone else's approach.

Install

I'm using the chartjs-chart-financial plugin so, first step is to install Chart.js and all necessary dependencies.

yarn add chart.js luxon chartjs-adapter-luxon chartjs-chart-financial

Note: If you're using React or Vue there's a good chance you'll be better off installing and using a React wrapper or Vue wrapper.

Initialize

Add this to application.js (or similar entrypoint to the app).

import Chart from 'chart.js/auto'
import * as luxon from 'chartjs-adapter-luxon'
import * as finChart from 'chartjs-chart-financial'

// Register the plugin's custom controllers
Chart.register(finChart.CandlestickController, finChart.CandlestickElement)

// Ensure the Chart class is loaded in the global context
window.Chart = Chart

Usage

I'm on Rails and using Hotwire, so my JavaScript code lives in Stimulus controllers.

I can use the Chart class from a connect() method in my controller because it was loaded globally. Each page visit includes the controller and the chart's data it needs in the HTML itself.

// `this.canvasTarget` references the Chart.js canvas HTML element
// this might differ depending on your framework (or lack thereof)
var ctx = this.canvasTarget.getContext('2d')

// `this.dataTarget` references the JSON data embedded in the HMTL
var data = JSON.parse(this.dataTarget.innerHTML)

// Traditional Chart.js usage but with a plugin's custom Chart type
var myChart = new Chart(ctx, {
  type: 'candlestick',
  data: {
    datasets: [ ... ] // <- data goes here
  },
  options: { ... }
})

Official docs here for Chart.js specifics

That's it

With some data and options added to the chart you're all set. The example below has line charts overlayed with the Candlestick chart.

Architectural choices & tradeoffs (RoR specific)

Embedding a large-ish JSON dataset in the HTML, times the number of charts in each page makes the HTTP response sizes larger than with an alternative approach (i.e. async API request). This problem likely increases the perceived response times, more so in slower connections.

Concious of this performance penalty I decomposed the charts in separate endpoints using lazy loaded frames.

This is also nifty for caching purposes since the chart's dataset is cached with (inside) the HTML response itself. Chart.js is initialized only once in the app's lifetime and is ready to use as soon as the controller renders on screen, ideally via cached network request.

Kudos

I found help and inspiration in @wanderingsoul's Chart.js post, Chart.js/Hotwire's docs, the plugin's GitHub docs, and lots of trial & error 🙃

Pura vida.

Integrating the Passport with the Forem Ecosystem

Fernando — Mon, 06 Dec 2021 17:18:57 +0000

This is the second post of a series that covers the new Forem Passport service provider, which integrates with the Forem open source software behind DEV and other communities.

Upcoming Forem Passport Projects

This service provider is such an exciting project in my view, because of the power and flexibility baked into the OAuth protocol. Not only does it help solve a problem we had (i.e. compliance and support across different platforms), it also interacts with many different core and ecosystem projects.

Some of the projects that relate to Forem Passport in one way or another are:

Android Mobile App

We just released the first few versions of our beta Android app!

Are you interested in being part of the closed beta? Do you want to be notified when the open beta rolls out? Drop a comment below and we’ll contact you.

iOS Mobile App

Version 1.2.2 includes the Passport integration already! Try it out now

Better Tooling for Creators to Fight Abuse

In a network of Forem sites, smaller instances might benefit from abuse control measures taken in bigger instances, like DEV. This could include propagation of banished users (at least to flag as likely abusers) throughout the network, making everyone safer.

⚠️ Abuse in this case refers to anything that doesn’t adhere to the Forem's code of conduct or terms and conditions.

Please note that this is still in ideation and hasn’t yet been discussed in great depth.

Better Integration Between the Passport and the `/admin` Dash for Creators

We can automate the process of enabling the Forem authentication for a creator (directly from their /admin dashboard) a lot more than its current form.

This idea has definitely been discussed and it’s actually a high priority goal. We want to make it as easy as possible for creators to enable the Forem passport integration so more users can benefit from it across the ecosystem.

Push Notifications for Mobile Apps on Self-Hosted Forems

We can’t openly give out our PN certificates to deliver push notifications to self hosted Forems. So, in order to overcome this we could rely on the authorization and not authentication aspect of the OAuth protocol.

The objective of this project is to implement a mechanism relay PN delivery to the Passport via API calls if the certificates aren’t available (self hosted sites).

This would only work for users that have connected their accounts with the Passport, because that’s the key part of how we would avoid abuse from any bad actor if they happen to spam their users.

Allowing for Social login within Forem Passport itself

We heard you like service providers, so we’re planning to integrate service providers on our service provider 😆

In all seriousness, since we have more control over Forem Passport, we could implement many customized authentication providers and make them compatible with our whole ecosystem (i.e. mobile apps).

Easier account management across many Forem sites

You could in theory propagate a new profile picture across many Forem sites at once, directly from Forem Passport.

This isn’t implemented and hasn’t even been discussed in depth either, but OAuth should allows us to make some of these integrations possible.

Open sourcing the Passport codebase

The core Forem software has been open source for a while now, and we want to open source this project as well in the near future for many reasons.

Our intention is to solidify the Passport project a bit more (i.e. have better abuse control) and other details sorted out before publishing the repo. We’ll be sure to communicate when this happens!

Invitations & Closing Note

Phew! We've covered a lot in this series so far. 😄

Invitations:

We’re interested in your feedback on all of the above, so please share your thoughts with us in the comments below.
Do you already have an account on https://passport.forem.com? Please leave us a comment below! What are your thoughts? Which upcoming project from the list above interests you most? Any other crazy ideas you might think would be cool to integrate with the Passport project?
Try it out Version 1.2.2 of the Forem iOS app, which includes the Passport integration
Reminder that you can comment below if you'd like to be part of our closed beta test for the Forem Android app

Closing Note:

We’re actively working on Forem Passport (i.e. design overhaul, abuse control features, new integrations, etc) so expect changes, big and small, to roll out on a weekly basis.

In the next post in this series, I’m going to explain how we managed to implement the Passport project from a technical perspective. Keep an eye out for it in the next few days.

Forem’s Approach to Decentralized Authentication and Authorization

Fernando — Mon, 06 Dec 2021 17:18:40 +0000

This is the first part in a series that will cover the new Forem Passport service provider, which integrates with the Forem open source software behind DEV and other communities.

A Brief History of Our Authentication Options

Since its early days, DEV relied solely on authentication providers to set up and access user accounts. There are pros and cons with that decision, but I’d say it’s working well, overall, with over 756,805 registered users (and counting!) today.

After DEV became part of the larger Forem umbrella, we’ve continued to expand from GitHub and Twitter authentication to allowing many other use cases like invite only (private) or email+password registration, to name a few.

Despite these new authentication options, our backend implementation of them hasn’t changed much. This is because we rely on OAuth (an open-standard authorization protocol/framework) and a polymorphic approach, which allows our team to add new providers that adhere to the OAuth protocol.

Below, I'll explain how these authentication factors connect with external influences (like Apple and Facebook), leading us to build our own authentication provider. If you’re more interested in the implementation (show me the code), check out the next part in this series, coming soon!

How Forem is Decentralized

Empowering community by giving ownership to creators (decentralization) is the bedrock of Forem's mission. Anyone that hosts their own Forem site becomes part of the world wide web (WWW), just like any other website does. It becomes a bit more interesting when we look at the network of Forem sites.

In case you missed it, a while ago we announced how you can now self-host your own Forem. Starting your own community with data ownership and the transparency of the open source (much like DEV) is finally possible 🌱

Forem Self-Host is Now Officially Supported

Ben Halpern for The DEV Team ・ Jul 20 '21

#forem #opensource #news #meta

Since we now have a network of sites that run Forem's open source community software, we need to work on the ecosystem around it. So we shipped the Forem iOS app with this in mind.

Forem's Approach to Decentralized Social Media on Mobile

Ben Halpern ・ Jun 3 '21

#meta #forem #ios #mobile

Forem for iOS means that you can browse many different Forem communities in one centralized app on the go. Since the days of our DEV iOS app (soon to be sunsetted), we have enhanced the mobile browser experience with Push Notifications and many more features. Together, we've accomplished all of this despite relying on a WebView-based implementation, which might be a sensitive topic at times... but that’s a post for another day 😅

Authentication Hurdles: Apple and Facebook

Since a Creator has full ownership of their Forem, we can’t control the authentication methods they choose to enable (this is the point). Apple, on the other hand, requires everyone using their authentication to comply with their guidelines.

We actually ~~ranted~~ joked a little about the “SIWA rule” in a DEV Twitch Stream a while ago, along with other mobile/ecosystem related conversations. SIWA is the acronym we use for Sign In With Apple.

Because Apple requires every iOS app that allows for social logins to have SIWA enabled, the Forem iOS app is being rejected by AppStore reviewers when they find some Forems listed in the app don’t have SIWA enabled by choice.

Despite being less than ideal, we had to hide all social authentication providers if the Forem site doesn’t have SIWA enabled within the ForemWebView context (which means it’s being rendered in a mobile app). This is the PR for that in case you’re curious.

Later, Facebook shut down their OAuth flow protocol in Android WebView contexts. According to them, this was a decision made “for security reasons”. This is the issue where some of this conversation has taken place. Similar to the SIWA situation, we’re not able to show the Facebook auth option.

Authentication on a Decentralized Network of Forem Communities

With these challenges led us back to a big picture idea discussed over year ago: an SSO solution that would work across Forems. The goal is to make authenticating with any Forem site easier — on any platform or context. Enter Forem Passport.

OAuth is incredibly powerful and even somewhat democratic, in the sense that each individual user chooses to authorize or revoke the permissions they’ve given through the OAuth protocol.

The iOS mobile app now integrates directly with Forem Passport and we’ve started to reach out to creators so they can enable the Forem authentication provider to allow for this better experience across platforms.

On some Forem sites like DEV, CodeNewbie and forem.dev, you can already connect your Forem Passport account from your settings or directly register a new account using the Forem auth provider.

In the next post in this series, I’m going to share the ongoing and upcoming projects we're working on, all of which integrate with the Passport project in one way or another. Read all about it here

DEV Community: Fernando

[Boost]

Why Infrastructure Engineers Should Start with Backend Development

Selfhost Timetagger on a Raspberry Pi

Timetagger

Requirements

Run the server

Cloudflare Tunnels

systemd services

Performance

Conclusion

Keeping up with my cat's 💩 using a RaspberryPi

The hero/villain of the story

Automating the extractor fan

fdocr / pir_trigger

Script that connects a PIR Sensor to a webhook

PIR Trigger

Usage

Sensor to board connections

It works!

💩 Stats

Background jobs for Kemal server in Crystal lang

Mosquito

Worker

Dockerfile

Resource consumption & performance

Telemetry comparison

Conclusions

Database for Kemal server in Crystal lang

Jennifer.cr

Migration & Model

Performance impact

How to recover/regain performance

Algorithms and standard library modules in my Battlesnake

Parsing JSON in Crystal

A* Search Algorithm

Comparing points (distance)

Flood fill

Conclusions

Documenting a Crystal open source project

Documenting code

GitHub Actions ➡ GitHub Pages

What it looks like

Deploy a Crystal app with Docker and Opentelemetry

Learning Crystal with Battlesnake

Fernando ・ Feb 14 '23

Digitalocean App Platform with Dockerfile

Opentelemetry

Learning Crystal with Battlesnake

The app

Strategies & Algorithms implemented

Leaderboard results

Conclusions

Using Chart.js plugins with webpack

Install

Initialize

Usage

That's it

Architectural choices & tradeoffs (RoR specific)

Kudos

Integrating the Passport with the Forem Ecosystem

Upcoming Forem Passport Projects

Android Mobile App

iOS Mobile App

Better Tooling for Creators to Fight Abuse

Better Integration Between the Passport and the /admin Dash for Creators

Push Notifications for Mobile Apps on Self-Hosted Forems

Allowing for Social login within Forem Passport itself

Easier account management across many Forem sites

Open sourcing the Passport codebase

Invitations & Closing Note

Forem’s Approach to Decentralized Authentication and Authorization

A Brief History of Our Authentication Options

How Forem is Decentralized

Forem Self-Host is Now Officially Supported

Ben Halpern for The DEV Team ・ Jul 20 '21

Forem's Approach to Decentralized Social Media on Mobile

Ben Halpern ・ Jun 3 '21

Authentication Hurdles: Apple and Facebook

Authentication on a Decentralized Network of Forem Communities

Better Integration Between the Passport and the `/admin` Dash for Creators