DEV Community: Chris Dawkins

Posta: Building a Social Blogging Backend with SurrealDB, Nix, and Nushell

Chris Dawkins — Tue, 13 May 2025 18:02:55 +0000

This is a quick blog about my experience building a social blogging backend with SurrealDB.

I have a personal project that needs a way of simply storing and organizing text posts with the ability to perform full-text-search on these posts. I decided to dive deeper into SurrealDB and, after the obligatory feature creep, built an open source solution that does all this and more!

What is Posta?

Posta is a social blogging backend built with SurrealDB. The project consists of a SurrealDB schema and uses Nix and Nushell to setup and run tests to assert correct functionality.

Some of the features that Posta offers:

User signup/signin
Publish/edit posts
Leave comments
Favorite posts
Subscribe to authors/tags
Blocking/muting
Full-text-search

The Stack

SurrealDB

SurrealDB offers several features that make it a strong candidate for building a database backend:

Multi-Model Database: SurrealDB supports multiple data models, including document-based, graph-based, and relational data.
Full-Text Indexing: SurrealDB provides full-text indexing capabilities, allowing efficient searching through text content.
Advanced Access Permissions: SurrealDB offers customizable access permissions at both the table and row levels.
Live Queries and Real-Time Data Sync: SurrealDB supports live queries and real-time data synchronization, allowing users to receive updates as soon as they occur.

You can load posta.surql into the Surrealist app to explore and learn more about Posta.

Nushell

Nushell has built-in testing, http, and data handling, making it a suitable choice for writing tests.

The tests are just scripts that setup the environment, run tests, and then teardown.

Nix

Nix is a package manager and build tool that is useful for bundling everything together in a reproducible way.

A note about contributing to open source

While doing research for these projects I came across some small bugs in another project. I made the fixes and opened some PRs which were accepted.

Programmers can be intimidated or unsure of where to start with open source contributions. You can discover many small bugs or typos while reading documentation or source code. These contributions are small but often times are also meaningful. So, don't be afraid of starting small!

Schema Design

The schema leverages heavy use of graph-based design to allow for bi-directional queries, compositional design, and relationship properties.

Simple authorization is done using the PERMISSIONS clause with more complex authorization handled using EVENT.

Below is an visualization of the schema using Surrealist:

Usage

Here are a handful of code snippets and usages.

New user

curl -X POST -H "Accept: application/json" -d '{
    "ns":"posta",
    "db":"posta",
    "ac":"Author",
    "user":"john.doe",
    "email_address":"john.doe@example.com",
    "pass":"123456"
}' http://localhost:8000/signup

User Signup

Implementation within Posta:

DEFINE ACCESS Author ON DATABASE TYPE RECORD
    SIGNIN (
        SELECT * FROM Author WHERE email IS $email AND crypto::argon2::compare(pass, $pass)
    )
    SIGNUP (
        CREATE Author CONTENT {
            name: $name,
            email_address: $email_address,
            pass: crypto::argon2::generate($pass),
        }
    );

ACCESS

New Post

Using a built-in function to make a new post

fn::Post::new($body, $title, $tags)

Function definition in schema:

DEFINE FUNCTION fn::Post::new($body: string, $title: string, $tags: array<string>) -> object {
    LET $post = CREATE ONLY Post CONTENT {
        body: $body,
        title: $title,
    } RETURN AFTER;

    FOR $tag IN $tags {
        LET $tag = string::lowercase($tag);
        -- Make new `Tag` if `$tag` doesn't exist
        IF (array::is_empty(SELECT * FROM Tag WHERE tag IS $tag)) {
            CREATE ONLY Tag CONTENT { tag: $tag };
        };

        LET $post_id = $post.id;
        LET $tag_id = (SELECT id FROM Tag WHERE tag IS $tag);

        RELATE $post_id->tagged->$tag_id;
    };

    RETURN $post;
} PERMISSIONS FULL;

FUNCTION

Edit Post

UPDATE $post_id MERGE {body: $body}

EVENT that checks for authorization and creates a diff object when a post is edited.

DEFINE EVENT post_edited ON TABLE Post WHEN $event IS "UPDATE" THEN {
    IF array::is_empty(SELECT id FROM published WHERE in IS $auth.id AND out IS $value.id) {
        THROW "Cannot edit unowned resource";
    };

    RELATE ($auth.id)->edited->($value.id) CONTENT {
        diff_ops: value::diff($before, $after)
    };
};

New Comment

Using SurrealQL to make a comment

RELATE ($auth.id)->comment->$post CONTENT { message: $message }

Text Search

Searching titles

SELECT * FROM Post WHERE title @@ 'SurrealDB';

Rank-searching for Post content

SELECT search::score(1) AS score FROM Post
    WHERE body @1@ 'graph-based database'
    ORDER BY score DESC;

Search functions

Testing

Testing is done using Nushell to setup the environment, push queries over http, and assert conditions.

Here is a test function that tests comment posting:

@test
def comment_post [] {
    let database = surrealdb_setup

    let authors = $database.bind | make_random_authors 2 | each {|it| $it | insert bind ($database | get bind)}

    let post = make_new_post $authors.0 | get result
    let message = random chars

    let comment = {
        query: "RELATE ($auth.id)->comment->$post CONTENT { message: $message };"
        args: {
            post: ($post | get id)
            message: $message
        }}
        | send_query $authors.1
        | first

    assert equal $comment.status "OK"

    let comments = {
        query: "SELECT * FROM comment"
        args: {}}
        | send_query $authors.1
        | first

    assert equal $comments.status "OK"
    assert length $comments.result 1
    assert equal ($comments | get result | first | get message) $message

    surrealdb_teardown
}

These tests get wrapped with nix for CI and other uses.

checks = {
  posta-tests = with pkgs;
    stdenv.mkDerivation {
      inherit system;
      name = "posta tests";
      src = ./.;
      buildInputs = [
        nushell
        surrealdb
      ];
      buildPhase = ''
        ${nushell}/bin/nu \
          --no-config-file \
          ./tests/mod.nu
      '';
      installPhase = ''
        touch $out
      '';
    };
};

Conclusion

Don't be afraid of writing your own code and your own bespoke solutions instead of just prompting or using a pre-made solution. You can discover new projects, learn new techniques, gain valuable experience, and meet and collaborate with new people. It's fun to build new things and try new technologies!

Resume-md: Manage your resume with GitHub and Markdown

Chris Dawkins — Mon, 15 May 2023 17:10:11 +0000

What I built

This project allows you to write and maintain your resume in markdown. GitHub Actions is used to generate stylized PDF and HTML files based on resume.md and style.css. The stylized files are found as outputs in the Releases section, the HTML file is also deployed as a static website using GitHub Pages.

Category Submission: DIY Deployments

Link:

siph / resume-md

Use markdown to generate a stylized resume in PDF and HTML and deploy a static site using GitHub Pages.

Resume-md

This project is useful for anyone looking to create a professional-looking resume quickly and easily, and is especially beneficial for those with technical backgrounds who are familiar with markdown. With this project, you can focus on the content of your resume rather than worrying about formatting and deployment.

Usage

GitHub

Generate a new project using this repository as a template. Make sure to include all branches!
Enable Read/Write Workflow permissions under Settings -> Actions for Pages deployment.
Edit the resume.md file with your resume content using Markdown.
Commit and push the changes.
Wait for the GitHub…

View on GitHub

About

I have seen other projects that provided some of the same features but I wanted something that automatically deployed via GitHub Pages. Unfortunately those projects were not licensed so I didn't feel comfortable forking them. Instead I decided to build my own solution from scratch and used the opportunity to make heavy use of nix throughout the process.

Nix

If you don't know about nix, I wrote ~~some propaganda~~ an article introducing some features that nix offers.

Resume-md uses nix for both dependency management and as a build system. The build process just consists of running a pandoc command to make the html file and a wkhtmltopdf command to build the pdf file. This nix derivation just runs those commands and moves the resulting files so that they're accessible in the nix store via /nix/store/${resume-md}/resumes/.

{
packages = {

  default = stdenv.mkDerivation {

    name = "resume_md";
    src = ./.;

    buildInputs = [
      pandoc
      wkhtmltopdf-bin
    ];

    buildPhase = ''

      pandoc resume.md \
      -t html -f markdown \
      -c style.css --self-contained \
      -o resume.html

      wkhtmltopdf --enable-local-file-access \
      resume.html \
      resume.pdf

    '';

    installPhase = ''

      mkdir -p $out/resume
      cp resume.* $out/resume/

    '';

  };
};
}

Using nix flakes to manage the dependencies means that each dependency is pinned to a specific commit which results in an extremely reproducible build process. You can run this build process locally to build the files which get placed into the nix store and symlinked to ./result.

GitHub Actions

The GitHub Actions marketplace is incredibly expansive and includes multiple options for including nix in your Actions. This makes it trivial to leverage all the powerful nix stuff already in place.

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - uses: cachix/install-nix-action@v19
      with:
        github_access_token: ${{ secrets.GITHUB_TOKEN }}
    - name: Build Resume
      run: |
        mkdir out
        nix build
        cp result/resume/resume.html out/${{ github.actor}}_resume.html
        cp result/resume/resume.pdf out/${{ github.actor}}_resume.pdf
        cp result/resume/resume.md out/${{ github.actor}}_resume.md
    - name: Store Artifacts
      uses: actions/upload-artifact@v3
      with:
        name: resume
        path: out/

Look at how simple this Action is as a result of the nix integration. It just tells nix to build the default package and copies/renames the files to prepend the GitHub username to the build artifacts.

GitHub Pages

This build process already outputs an html file so it makes perfect sense to deploy it as a static website using GitHub Pages.

jobs:
  publish:
    runs-on: ubuntu-latest
    needs: generate
    steps:
    - uses: actions/checkout@v3
    - name: Retrieve Artifacts
      uses: actions/download-artifact@v3
      with:
        name: resume
        path: out/

    - name: Stage
      run: |
        mkdir public
        cp out/${{ github.actor }}_resume.html public/index.html
    - name: Deploy
      uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: ./public

This also uses the hub cli tool, available in any Actions environment, to build a release for the user to download the html, pdf, and original md files. This generates a time-stamp for the release title and adds the resume files, all without needing to manually make and push tags.

    - name: Set Tag
      id: current-datetime
      run: echo "CURRENT_DATETIME=$(date +'%Y-%m-%d-%H_%M_%S%z')" >> "$GITHUB_OUTPUT"
    - name: Build Release
      shell: bash
      run: |
        hub release create ${{ steps.current-datetime.outputs.CURRENT_DATETIME }} \
        -m ${{ steps.current-datetime.outputs.CURRENT_DATETIME }} \
        -a out/${{ github.actor }}_resume.html \
        -a out/${{ github.actor }}_resume.md \
        -a out/${{ github.actor }}_resume.pdf
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Conclusion

GitHub Actions is an awesome automation platform and combined with nix provides and incredible toolkit to build powerful, reproducible and streamlined pipelines.

Writing Polybar Modules in Nushell

Chris Dawkins — Wed, 26 Apr 2023 14:30:53 +0000

Polybar modules are almost always written in either bash or python. Bash offers an ubiquitous, stable platform and python, a large ecosystem and much nicer syntax. I want to show how nushell can serve as another alternative.

Building the Module

The sample module is simple. It queries a GitHub repository for an RSS document and prints how much time has elapsed since the last update.

# elapsed.nu


#!/usr/bin/env nu

# Returns how long it has been since a repository received its last update.
def main [
    --user: string,         # GitHub username
    --repository: string    # User repository
] {
    let elapsed = (http get $"https://github.com/($user)/($repository)/releases.atom"
        | from xml
        | get content
        | where { |it| $it.tag == `updated` }
        | $in.content.0.content.0
        | into datetime
        | date humanize)
    print $"($user)/($repository) was updated ($elapsed)."
}

I'm not going to get into the syntax of nushell but here is a summary of what this script does:

Make a web request.
Load the RSS response as structured data.
Filter and traverse the data structure to access values.
Convert a string into a workable datetime object.
Determine the amount of elapsed time.
Print an interpolated message.

This isn't anything that couldn't be done with python or bash, but nushell has some advantages that makes it a compelling option in this instance.

First, nushell is able to do all of this without any external dependencies. An http call would need a dependency or significantly more lines in python and bash would offload the task to curl. Deserialization is also non-trivial in python and bash even with dependencies.

Nushell also has a nice syntax, certainly better than bash. With a functional approach and lots of high-level functionality, powerful operations can be done with relatively small amounts of code.

There are also constant improvements and changes to the language/shell because nushell is fairly young and still in very active development. The downside is that this does result in nushell being far less stable than the others.

Using the Module

Polybar uses the module the same way it would any other module.

[module/elapsed]
type = custom/script
interval = 600
exec = ~/scripts/elapsed.nu --user nushell --repository nushell

Now its ready to be added to your bar. Here it is in my config.

This isn't a very useful module and only meant as a demonstration, but the weather and clock modules are also written in nushell.

#clock.nu


#!/usr/bin/env nu

# Get date and time as string with format.
def main [
    --format: string = "%a ● %D ● %r";  # Output string display format. Default: `%a ● %D ● %r`.
] {
    date now | date format $"($format)"
}

#weather.nu


#!/usr/bin/env nu

# Query `wttr.in` for weather report with location and format.
def main [
    --location: string,                         # Can be city name or ICAO code.
    --format: string = "%c%t ● %h ● %w ● %m";   # Optional output string display format. Default: `%c%t ● %h ● %w ● %m`.
] {
    http get $"https://wttr.in/($location)?format=($format)"
}

Conclusion

You could really use whatever you wanted to build these simple modules. You could build a java app and run the jar in the configuration file as long as it prints to stdout. The reason people choose python or bash is the same reason they choose them for any other script. Nushell is nice to work with on both the command line and when building scripts and it makes a great tool to build polybar modules.

Declare and version control you tmux sessions

Chris Dawkins — Sun, 16 Apr 2023 20:40:42 +0000

Anyone who spends a significant amount of time in the command line understands how tedious and cumbersome managing multiple tmux sessions can be. Many programmers find themselves switching between a variety of projects of different languages and sizes on a daily basis. With tmuxp you can declare what a tmux session for a project should look like using json/yaml.

A simple declaration that fetches from a remote repo and opens neovim in one window with bottom running in a second.

# ~/example/.tmuxp.yaml
session_name: Swoll Sesh
start_directory: ~/example
windows:
    - window_name: nvim
      panes:
        - shell_command:
          - git fetch
          - nvim .
    - window_name: monitor
      panes:
        - shell_command:
          - btm

To start this session just run:

tmuxp load ~/example

This file can then be version controlled, keeping your developer environment organized, consistent and reusable. You can find more examples in the documentation

Combining this with one of the session management plugins for neovim/vim means that your editor will automatically open where you want it.

This can be even further expanded with nix, flakes, direnv, and nix-direnv to give you a fully automated and reproducible developer environment complete with the environment variables and dependencies needed to start hacking on a project.

Hi There! Have You Heard The Good News About Our Lord And Savior Nix?

Chris Dawkins — Tue, 28 Feb 2023 02:30:08 +0000

It seems like there is a lot of buzz lately around Nix and NixOS. It keeps popping up more and more as a topic of discussion, especially with software developers. However, looking at it's surface and trying to understand what Nix even is can be a struggle. Nix is expansive and knowing what problems it solves and how to even begin to approach the ecosystem can be challenging. This guide is intended to be an introduction and brief exploration into what Nix/NixOS is and how it can benefit you as a developer.

What is Nix?
- Difference Between Nix and NixOS
System Management
- User
  - Home Manager
  - Nixos-Generators
- Server
Nixpkgs
- Packaging Software
  - Flakes
Development Environment
- Devshell
Learning Nix

What is Nix?

Nix is a purely functional package manager and operating system deployment tool. It was designed to manage the configuration and installation of software on a variety of operating systems, including Linux, and macOS.

Nix's distinguishing feature is its functional approach to package management. Instead of the traditional approach of installing packages into a global system directory, Nix packages are built in isolation and stored in a per-user store. This means that multiple versions of a package can coexist on the same system, and dependencies are managed in a consistent and predictable way.

Here are some reasons why someone might want to use Nix:

Reproducible builds: Nix ensures that every package build is isolated and uses exactly the same dependencies, making it easy to reproduce builds across different machines.
Multiple versions: Nix allows you to have multiple versions of the same package installed at the same time, which is useful for development and testing.
Declarative package management: Nix uses a declarative language to describe package dependencies and configurations, making it easy to specify exactly what you want installed on a system.
Rollbacks: Nix allows you to roll back to a previous system configuration if something goes wrong, which can be a lifesaver in production environments.
Cross-platform support: Nix works on a variety of operating systems, so you can use the same package management tool across different machines.
Massive package repository: Nix has a huge repository of pre-built packages, which can save time and effort in setting up a new system or developing software. See how nixpkgs compares to your package manager.

Difference Between Nix and NixOS

Nix is a package manager for Linux and other Unix-like systems that allows for declarative, reproducible, and isolated software installation and configuration.

NixOS, on the other hand, is a Linux distribution that uses Nix as its package manager and is built around the principles of declarative system configuration and functional package management. NixOS uses a declarative language (also confusingly called Nix) to describe system configuration, including the installation and configuration of packages, users, network interfaces, and other system components. This makes it easy to reproduce a system's configuration and to roll back to a previous configuration if necessary.

In other words, while Nix is a package manager that can be used on any Linux or Unix-like system, NixOS is a complete Linux distribution that uses Nix as its package manager and has a unique approach to system configuration.

System Management

One of the most appealing features of Nix/NixOS that tends to draw new users in is the ability to have your entire system configuration written out and version controlled. This means that your entire fully configured system is ready to deploy anytime, anywhere right from a git repository. This even includes things like SSH or PGP keys by using agenix.

User

Using Nix as a package manager and configuring your home applications with home-manager means that your configuration can be deployed outside of NixOS. Nix can reproduce a configuration on Ubuntu, Fedora, etc. as well as macOS. This can allow users to leverage some strengths of Nix without diving all the way into the ecosystem.

Home Manager

Home-manager is a tool for managing user-specific configuration files on top of the Nix package manager. It allows users to declaratively manage their user environment, including their shell configuration, editor configuration, and other user-specific settings.

Home-manager extends the power of NixOS system management to user management letting you declaratively configure your home applications.

Some examples of what you can do with Home Manager include:

Configuring your shell (e.g. zsh or bash or nushell) with custom settings and plugins
Installing and configuring your favorite text editor (e.g. Neovim or VSCode) with custom settings and plugins
Configuring your development tools (e.g. Git or Docker) with custom settings and aliases

Nixos-Generators

Nixos-generators can be used to generate a plethora of formats including ISO. Meaning you can keep a configuration that's specific to your needs and have it handy on a thumb drive.

You can also build a server configuration and have a cloud image (digitalocean, aws, etc) uploaded and ready to deploy on-demand.

Server

NixOS really shines when used to build application infrastructure. Things like firewalls, databases, reverse-proxies, and environment variables can all be configured using NixOS declarative module system.

Using NixOS for server configuration provides several other benefits, including:

Declarative configuration: NixOS modules provide a declarative way to describe server configuration, allowing you to specify exactly what software should be installed, how it should be configured, and what services should be running on the server. This makes it easy to reproduce server configurations across different machines, and ensures that server configuration is always consistent and predictable.
Modularity: NixOS modules are designed to be modular, with each module responsible for configuring a specific aspect of the server. This makes it easy to manage complex server configurations, and allows you to reuse configuration across different servers.
Reusability: NixOS modules can be reused across different server configurations, making it easy to share configuration between different projects and teams.
Versioning: NixOS modules are versioned, making it easy to track changes to server configuration over time and to roll back to previous configurations if necessary.
Safety: NixOS modules are designed to be safe, with built-in checks to prevent invalid configurations and to ensure that server configuration is consistent and predictable.

Nixpkgs

Nixpkgs currently has more software packages than any other package repository (excluding the npm madhouse). The packages also tend to be very fresh and up-to-date thanks to the community and projects like nixpkgs-update.

Packaging Software

Packaging software for Nix involves creating a Nix derivation, which is an expression that describes how to build and install the software. In this expression you provide a list of dependencies as well as instructions on how the software should be built. There are many helpful tools to make building common project types like cargo, poetry, or go projects much simpler.

Flakes

Nix Flakes is a new feature that was introduced in Nix version 2.4. It's a way to make Nix more composable and modular, and to simplify the process of managing and distributing Nix configurations as well as achieving strict reproducibility through a lock file.

At a high level, Nix Flakes allow you to specify a set of inputs (e.g. Nix packages or other Flakes) and a set of outputs (e.g. a configuration for a specific system or environment). You can then use these inputs to build your outputs, and share your configuration as a single, self-contained unit that can be easily distributed and reused.

Flakes have created somewhat of a schism in the Nix community although adoption continues to increase as Flakes reduce or eliminate many of the pain-points experienced while working with Nix.

Development Environment

Nix is a developers dream. There is a staggering amount of tooling, utility, and clever mechanisms that can provide enormous amounts of value and productivity to a project. Using Nix, Flakes, and Devshells can eliminate the worry of dependencies and versions inside a developers' environment.

Devshell

Devshells are a feature of Nix that allow you to create a shell environment with all the dependencies and environment variables needed for a particular project or task. Devshells are useful for developers who work on multiple projects or who need to switch between different programming languages or development environments frequently.

They're also useful as a means of unifying dependencies and development environments in a consistent and reproducible way. By defining the dependencies and environment in a Nix expression, you can ensure that all developers on your team are using the same versions of libraries and tools, and that the environment can be easily recreated on different machines or platforms.

This can be further extended into automation environments like CI/CD pipelines and even into production.

Combined with Flakes, Devshell dependencies can all be pinned to specific versions for extremely consistent reproducibility which virtually eliminates the 'works on my machine' dilemma.

Learning Nix

Overall, Nix and NixOS offer many benefits for developers, including reproducible builds, isolation, easy package management, and rollback capabilities. These features can help developers be more productive and efficient, and make it easier to collaborate on software projects with others.

However, Nix has a pretty notorious reputation for being difficult to grasp. The learning curve for Nix and NixOS can be steep, especially for developers who are new to functional programming and declarative configuration management.

Documentation for NixOS is mostly adequate in 2023 although oftentimes scattered around the internet.

Despite these challenges, many developers find that the benefits of using Nix and NixOS outweigh the learning curve. Once developers become proficient with Nix and NixOS, they can enjoy the benefits of reproducible builds, isolation, easy package management, and rollback capabilities, among others.

Links:

awesome-nix: Officially curated list of Nix resources.
nixpkgs: Software repository for Nix.
wiki: Official NixOS wiki.
discourse: NixOS community discussion.
nixos-search: Search nixpkgs from the web.

Leverage Markdown and GitHub to Manage Your Resume with Resume-md

Chris Dawkins — Thu, 23 Feb 2023 18:17:14 +0000

Many developers are very familiar with benefits of markdown. It has a simple syntax which makes it easy to learn, read, and write. It's also very easy to version control and with a tool like Pandoc, can be combined with css to build stylized outputs in multiple formats like PDF and HTML.

This, combined with GitHub Actions and GitHub Pages can be leveraged to automatically build a stylized PDF for download, and deploy a stylized HTML as a static web page.

Resume-md

Resume-md is a project that automates resume management and does all these things for you.

How To Use

Generate a new project using resume-md as a template.
Make sure to include all branches.
Enable read/write workflow permissions.
Edit resume.md and push commits. Optionally, you can also edit
style.css.
Once finished, download your PDF/HTML from the Actions tab.
The HTML is automatically deployed to
https://<your-github-username>.github.io/<repository-name>

Conclusion

This approach has a lot of benefits especially to developers who are already comfortable with markdown and using git. Adding the automated processes using GitHub's tooling is an added layer of convenience and speaks to the power of the platform. This makes it trivial to keep your resume looking good and up to date.

Working with JSON in the command line with jq

Chris Dawkins — Mon, 26 Sep 2022 14:06:37 +0000

JSONs versatility makes it a great choice for many things beyond web communications. Configuration files and logging
files are two things that often are written in, or contain JSON. Working with these files using traditional tools like
awk and sed is cumbersome and frustrating. This is where jq comes in.

What is `jq`?

jq is a JSON processing tool that uses a very high level, purely functional language to query, mutate, and create
JSON. Utilizing the familiar concepts of pipes, filters, and streams; jq accepts expressions written in the JSON-like
syntax unique to jq.

Examples

jq can accept either a file that contains the JSON, or JSON piped through stdin. This allows you to do pretty cool
things like pipe the body of a curl request into jq, apply some business logic to derive a new JSON body, and pipe
that body back into another curl request to send to a remote server. The following examples are going to be ran
against some made-up status style JSON and fed in as a program argument. You can use jqplay
to try out jq in the browser and to help build complex commands.

# config.json
{
    "version": "22.04",
    "dimensions": {
        "width": 1920,
        "height": 1080
    },
    "devices": [
        {
            "id": 22,
            "state": "on",
            "group": 0,
            "status": "OK"
        },
        {
            "id": 422,
            "state": "off",
            "group": 0,
            "status": "OK"
        },
        {
            "id": 702,
            "state": "off",
            "group": 99,
            "status": "FAILED"
        }
    ]
}

Read Property

Expressions are passed into jq as a string. Because we are eventually going to be using double quotes to work with
nested strings, we can wrap everything in single quotes to avoid having to escape every quotation.

The dot operator is used to access the top-level entity within the scope. This gives us access the version property.

jq '.version' config.json

# output:
"20.04"

The truncate tool (tr) can be used to clean up the quotes

jq '.version' config.json | tr -d /"

# output:
20.04

Nested properties can be accessed like expected.

jq '.dimensions.width' config.json

# output:
1920

Arrays

Arrays can be iterated over by calling the array directly.

jq '.devices[]' config.json

# output:
{
    "id": 22,
    "state": "on",
    "group": 0,
    "status": "OK"
}
{
    "id": 422,
    "state": "off",
    "group": 0,
    "status": "OK"
}
{
    "id": 702,
    "state": "off",
    "group": 99,
    "status": "FAILED"
}

Arrays can also be indexed like expected.

jq '.devices[0]' config.json

# output:
{
    "id": 22,
    "state": "on",
    "group": 0,
    "status": "OK"
}

jq also supports slicing of both arrays and strings.

jq '.devices[:-1]' config.json

# output:
{
    "id": 22,
    "state": "on",
    "group": 0,
    "status": "OK"
}
{
    "id": 422,
    "state": "off",
    "group": 0,
    "status": "OK"
}

Pipes

The real power of jq starts with the pipe operator. Properties can be selected and then piped into the next expression.
The above example of iterating over an array can also be written using the pipe operator.

jq '.devices | .[]' config.json

# output:
{
    "id": 22,
    "state": "on",
    "group": 0,
    "status": "OK"
}
{
    "id": 422,
    "state": "off",
    "group": 0,
    "status": "OK"
}
{
    "id": 702,
    "state": "off",
    "group": 99,
    "status": "FAILED"
}

Accessing the state property of each object.

jq '.devices | .[] | .state' config.json

# output:
"on"
"on"
"off"

Filtering

jq has a number of built-in functions, one of which is select.
select accepts a boolean expression and returns if the condition evaluates to true.

Selecting all devices that are disabled and do not have a status of OK.

jq '.devices | .[] | select(.state=="off") | select(.status != "OK")' config.json

# output:
{
    "id": 702,
    "state": "off",
    "group": 99,
    "status": "FAILED"
}

Regex

Instead of comparing strings directly, jq has several regex functions with the simplest being test, which returns a
boolean if the input string matches the regular expression. The above filter can be rewritten using test.

jq '.devices | .[] | select(.state|test("off")) | select(.status|test("^((?!OK).)*$"))' config.json

# output:
{
    "id": 702,
    "state": "off",
    "group": 99,
    "status": "FAILED"
}

Building JSON

jq also lets you mutate and create JSON. Maybe you want to build a new JSON object using only two fields from the
source JSON. You can assign the parent property to a variable so that it is still accessible in the nested scope.

 jq '.version as $version | .devices | .[] | {device_id: .id, version: $version}' config.json

# output:
{
  "device_id": 22,
  "version": "22.04"
}
{
  "device_id": 422,
  "version": "22.04"
}
{
  "device_id": 702,
  "version": "22.04"
}

You can wrap the expression in square brackets to collect the objects into an array.

jq '[.version as $version | .devices | .[] | {device_id: .id, version: $version}]' config.json

# output:
[
  {
    "device_id": 22,
    "version": "22.04"
  },
  {
    "device_id": 422,
    "version": "22.04"
  },
  {
    "device_id": 702,
    "version": "22.04"
  }
]

Lets take the dimensions object and squash it into a new string to add to our objects. This time instead of
assigning a property to a variable, an entire JSON object is created to be referenced later. Parenthesis must be used to
group expressions together. The full expression is starting to get quite long so it's now broken up into multiple lines
and indented to be more readable.

 jq '
  [
    {
      version: .version,
      dimensions: ((.dimensions.width|tostring) + "x" + (.dimensions.height|tostring))
    }  as $extras
    | .devices
    | .[]
    | {
        device_id: .id,
        version: ($extras|.version),
        dimensions: ($extras|.dimensions)
      }
  ]' config.json

# output:
[
  {
    "device_id": 22,
    "version": "22.04",
    "dimensions": "1920x1080"
  },
  {
    "device_id": 422,
    "version": "22.04",
    "dimensions": "1920x1080"
  },
  {
    "device_id": 702,
    "version": "22.04",
    "dimensions": "1920x1080"
  }
]

Conclusion

This guide doesn't cover the full depth of jq but should be more than enough to get started doing some pretty cool
things. I've only just discovered jq but I can already see so many ways that it can benefit my workflow. There are
more features included in jq such as function definitions, conditionals, comparisons, and modification assignment
operators. You can find overviews of all these features and more in the jq manual.

Skylunch: API for aviators

Chris Dawkins — Sun, 28 Aug 2022 17:22:40 +0000

Overview of My Submission

Skylunch is a simple, non-blocking api built using Spring Webflux that, provided with an airport code, will return a list of restaurants with their ratings and other details.

Submission Category:

MEAN/MERN Mavericks

Language Used

Kotlin/Spring

Link to Code

siph / skylunch

Api to find restaurants near airports.

Skylunch

The $100 hamburger is a phrase used to describe a recreational flight taken by pilots for the primary purpose of having a meal at a distant airport The term is often used humorously to describe the high cost of general aviation, but it also represents the freedom and joy of flying for leisure.

Skylunch is a simple, non-blocking api built using Spring Webflux that, provided with an airport code, will return a detailed list of restaurants within a configurable radius.

The purpose of Skylunch is to help aviators find new and interesting destinations to elevate the enjoyment of their favorite hobby.

How it works

Technologies

Skylunch is built using the following technologies:

Data Storage and Access

Data is stored with Redis using Redis OM Spring.

Upon receiving a request, Skylunch will search the Redis cache/db for a result before…

View on GitHub

Check out Redis OM, client libraries for working with Redis as a multi-model database.
Use RedisInsight to visualize your data in Redis.
Sign up for a free Redis database.

Building a Tiling Window Manager with Rust and Penrose

Chris Dawkins — Tue, 17 May 2022 17:22:11 +0000

During the pursuit of increased productivity, many developers strive to eliminate their usage of the mouse as much as possible. The most effective way to eliminate a large percentage of your mouse usage is by switching from a traditional style of window manager to a tiling style window manager.

What is a tiling-window manager?

Traditional window managers follow a "floating" or "stacking" philosophy. These window managers were originally intended to mimic the familiarity of moving papers around a desk. A newly opened window in a floating-window manager has no regard for the state or visibility of the other opened windows. A tiling-window manager, however, makes the assumption that if a window is open, it should be visible. A newly opened window in a tiling-window manager will be placed in a tile along with the other windows, depending on the chosen layout. The opened windows can then be cycled though, moved, resized, and closed with the use of keyboard bindings. This takes much of the work usually done with the mouse and offloads it to the keyboard thus significantly increasing productivity.

Why Penrose?

There are many existing tiling-window managers with i3 probably being the most popular choice for linux systems. These window managers can depend on extensive configuration files or in the case of dwm, git patching or C programming. Penrose takes a different approach in that Penrose is not a window manager. Penrose is a high-level rust library that you use to
build your own window manager. This gives us many options for customization while also giving us all the advantages that come with writing rust code.

Prerequisites

X11

Penrose works for the X11 window management system. This means that your choice of operating system is basically only linux or bsd.

Rust

Some familiarity with rust is required. The Rust Book is the best place
to start.

Getting Started

To start, we're going to generate a new rust binary project using cargo with the command:

cargo new mywm

Dependencies

To build our window manager, we only need two dependencies. A logging library and penrose itself. Our needs are simple so we can just log to stdout. We will add these to our Cargo.toml.

Cargo.toml

penrose = "0.2"
simplelog = "0.8"

Styles

Before we start building the main application, lets make some modules which contain the styles that we are going to use. Let's create a styles module, which will make our file tree look like this:

mywm
│   Cargo.toml
└───src
│   │   main.rs
│   │   styles.rs

styles.rs

pub const PROFONT: &str = "JetBrainsMono Nerd Font";

pub mod colors {
    pub const BLACK: &str = "#000000";
    pub const GREY: &str = "#808080";
    pub const WHITE: &str = "#ffffff";
    pub const PURPLE: &str = "#a020f0";
    pub const BLUE: &str = "#0000ff";
    pub const RED: &str = "#ff0000";
}

pub mod dimensions {
    pub const HEIGHT: usize = 18;
}

In our styles module we can add our preferred font and submodules for some basic colors and dimensions. We can declare this module directly in our main file along with our intent to use them.

main.rs

mod styles;
use styles::{ PROFONT, colors, dimensions };

Hooks

Penrose supports the use of hooks to further modify the behavior of our window manager. For our purposes, we are only interested in creating a hook which will execute an external script upon startup. This script will allow us to do things like run feh to set our background, start window-compositors to enable window transparency, and more. We can create the hooks module the same way we created the styles modules, leaving our file tree looking like this:

mywm
│   Cargo.toml
└───src
│   │   main.rs
│   │   styles.rs
│   │   hooks.rs

hooks.rs

use penrose::{
    core::{
        hooks::Hook,
        manager::WindowManager,
        xconnection::XConn,
    },
    Result,
    spawn,
};

pub struct StartupScript {
    path: String,
}

impl StartupScript {
    pub fn new(s: impl Into<String>) -> Self {
        Self { path: s.into() }
    }
}

impl<X: XConn> Hook<X> for StartupScript {
    fn startup(&mut self, _: &mut WindowManager<X>) -> Result<()> {
        spawn!(&self.path)
    }
}

This is the entirety of our hooks module. First we declare a struct which holds the path to the script on our system. Then we implement the hook trait for penrose to spawn the process. We can declare this module in the main file the same way we did our styles module.

main.rs

mod hooks;

Main Application

Now we can move on to implementing the actual application logic. Everything from this point will be added to the main.rs file. To start, we are going to declare a few constant variables which will hold our choice of terminal, application launcher, and the path to our start script.

pub const TERMINAL: &str = "kitty";
pub const LAUNCHER: &str = "dmenu_run";
pub const PATH_TO_START_SCRIPT: &str = "$HOME/.mywm";

Replace these values with your preferred application choices and the path to your start script. These values could be declared programmatically through the use of something like the clap crate. This would have the benefit of externalizing our configuration, which would allow us to make changes without re-compiling the entire application. That would be beyond the scope of this tutorial. You can, however, find an example of this in my personal build: HERE.

Main Function Return Type

Our main function is going to return a penrose Result to make error handling much simpler.

fn main() -> penrose::Result<()> {
}

Logging initialization

use simplelog::{ LevelFilter, SimpleLogger };
...
if let Err(e) = SimpleLogger::init(LevelFilter::Info, simplelog::Config::default()) {
    panic!("unable to set log level: {}", e);
};

We are going to use the simplelog crate to initialize our logger. The SimpleLogger logs to stdout, if we wanted to log to a file we could replace it with WriteLogger.

Layouts

use penrose::{
    core::{
    layout::{
        LayoutConf,
        side_stack,
    },
    Layout,
    },
};
...
let side_stack_layout = Layout::new("[[]=]", LayoutConf::default(), side_stack, 1, 0.6);

For our purposes, we are only going to declare a single layout. This layout allows one main window and allocates 60% screen of the real-estate to the main window, and shares the remaining 40% between the other windows. The string is the symbol that will be displayed when the layout is active.

Config

use penrose::Config;
...
let config = Config::default()
    .builder()
    .show_bar(true)
    .top_bar(true)
    .layouts(vec![side_stack_layout])
    .focused_border(colors::PURPLE)?
    .build()
    .expect("Unable to build configuration");

This config is very simple. We allocate space for a top bar, add our layouts, and choose a border color which will appear around the active window.

Top-Bar

use penrose::{
    draw::{
        TextStyle,
        Color,
        dwm_bar,
    },
    xcb::XcbDraw,
};
...

let style = TextStyle {
    font: PROFONT.to_string(),
    point_size: 11,
    fg: Color::try_from(colors::WHITE)?,
    bg: Some(Color::try_from(colors::BLACK)?),
    padding: (2.0, 2.0),
};

let empty_ws = Color::try_from(colors::GREY)?;
let draw = XcbDraw::new()?;

let bar = dwm_bar(
    draw,
    dimensions::HEIGHT,
    &style,
    Color::try_from(colors::PURPLE)?,
    empty_ws,
    config.workspaces().clone(),
)?;

We could use something like polybar to build a powerful and sophisticated top-bar for our system. However, for this example we are going to use the built-in dwm_bar which mimics the bar that can be found in dwm. What's happening here is pretty straight-forward. First we populate the styling struct, and then we plug these values into the dwm_bar.

Keybindings

use penrose::{
    core::{
        ring::Direction::{
            Forward,
            Backward,
        },
        data_types::Change::{
            More,
            Less,
        },
        helpers::index_selectors,
    },
    Selector,
};
...
let key_bindings = gen_keybindings! {
        // Program launchers
        "M-p" => run_external!(LAUNCHER);
        "M-Return" => run_external!(TERMINAL);

        // Exit Penrose (important to remember this one!)
        "M-A-C-Escape" => run_internal!(exit);

        // client management
        "M-j" => run_internal!(cycle_client, Forward);
        "M-k" => run_internal!(cycle_client, Backward);
        "M-S-j" => run_internal!(drag_client, Forward);
        "M-S-k" => run_internal!(drag_client, Backward);
        "M-f" => run_internal!(toggle_client_fullscreen, &Selector::Focused);
        "M-c" => run_internal!(kill_client);

        // workspace management
        "M-Tab" => run_internal!(toggle_workspace);
        "M-A-period" => run_internal!(cycle_workspace, Forward);
        "M-A-comma" => run_internal!(cycle_workspace, Backward);

        // Layout management
        "M-grave" => run_internal!(cycle_layout, Forward);
        "M-S-grave" => run_internal!(cycle_layout, Backward);
        "M-A-Up" => run_internal!(update_max_main, More);
        "M-A-Down" => run_internal!(update_max_main, Less);
        "M-l" => run_internal!(update_main_ratio, More);
        "M-h" => run_internal!(update_main_ratio, Less);

        map: { "1", "2", "3", "4", "5" } to index_selectors(5) => {
             "M-{}" => focus_workspace (REF);
             "M-S-{}" => client_to_workspace (REF);
         };
    };

Penrose includes a helpful macro that allows us to quickly set our keybindings. The 'M' key is the meta key aka Windows key. We also label our workspaces here. We are only declaring 5, but you could use any arbitrary number of workspaces. We also label our workspaces with numbers, but they could be labeled using icons or emojis.

Hooks

use penrose::{
    core::{
        hooks::Hooks,
    },
    XcbConnection,
};
...
let hooks: Hooks<XcbConnection> = vec![
    Box::new(bar),
    Box::new(hooks::StartupScript::new(PATH_TO_START_SCRIPT)),
];

Here we create a vector to hold our hooks. We only have two hooks, the top-bar, and the start script we declared earlier.

Run

use penrose::{
    new_xcb_backed_window_manager,
    logging_error_handler,
};
...
let mut wm = new_xcb_backed_window_manager(config, hooks, logging_error_handler())?;
wm.grab_keys_and_run(key_bindings, map!{})

All that is left now is to build it and run it.

Additional Steps

Compiling and Running

Compilation is as simple as running the cargo build command:

cargo build --release

Now that we have a binary, how do we run it? We could use xinit to launch a session directly from a tty. Instead, if you already have a login manager installed, you can move the binary to the /usr/bin/ directory and make a mywm.desktop file that looks something like this:

[Desktop Entry]
Encoding=UTF-8
Name=Mywm
Comment=Tiling Window Manager
Exec=mywm
Type=Xsession

Place the .desktop file in /usr/share/xsessions/ directory, and you will be able to select mywm upon login.

.mywm Hook Script

We built a hook that would run our script on startup. The script can be used to do many things, but the most common would probably be to set your background.

 #!/bin/sh
 feh --no-fehbg --bg-scale '$HOME/Pictures/background.png'

Just make sure that .mywm has executable privileges.

Jetbrains IDE

Intellij along with other Jetbrains IDEs can have trouble when running under a tiling-window manager. To solve this problem, you need to export a variable for the JVM that runs the IDE to use:

export _JAVA_AWT_WM_NONREPARENTING=1

The best place to put this is in an .env file like .zshenv, if zsh is your default shell.

Conclusion

Building your own window manager can be a very daunting undertaking. With tools like Penrose, much of the complexities involved are hidden behind helpful libraries. This particular build only scratches the surface of what can be accomplished. The complete code for this project can be found on my gitlab alongside my actual build.

Easy and Advanced Neovim Setup with LunarVim

Chris Dawkins — Fri, 15 Apr 2022 21:48:49 +0000

Neovim is a lightweight and powerful text editor that can be a valuable addition to any developers toolbox.
Highly configurable and extensible, Neovim can be transformed from a simple text-editor into a full-featured development environment.
Configuring Neovim, however, can be a daunting and difficult task. Even maintaining a Neovim configuration can be a frustrating task in itself.
This is where LunarVim comes in.

What is LunarVim?

LunarVim is a project that aims to provide an easy and powerful configuration for Neovim.
Some useful features included in LunarVim by default are:

Language server provider (lsp) support.
Automatically installed language servers based on opened file extensions.
Treesitter support.
File tree browser.
Fuzzy searching.
Multiple default color themes.

Installing LunarVim

Dependencies

Upon reading the official documentation, we can see that LunarVim has a few dependencies.
On Ubuntu, node and npm can be installed by the package manager using the command:



sudo apt install nodejs npm

To install cargo we can use rustup by running the command:



curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

To avoid any permission issues, we can change the default directory that npm uses to store packages.
To change the default directory we can follow the guide in the npm docs.

Neovim

LunarVim requires version 0.5+ of Neovim to function.
A helper script is included in the LunarVim documentation to quickly install the correct version:



bash <(curl -s https://raw.githubusercontent.com/LunarVim/LunarVim/rolling/utils/installer/install-neovim-from-release)

Installation

Once that has been done, we are ready to install LunarVim.

I prefer installing from the rolling branch because the stable branch can feel neglected.



LV_BRANCH=rolling bash <(curl -s https://raw.githubusercontent.com/lunarvim/lunarvim/rolling/utils/installer/install.sh)

After installation we can finally run LunarVim with the command:



lvim

And we are greeted with the default welcome screen.

Configuring LunarVim

The default configurations are perfectly usable and capable of serious development right out of the gate.
However, with some simple changes we can make it more closely fit our preferences.

If we look in our user configurations files (~/.config/lvim/), we can see that LunarVim has generated a default configuration file.
After opening the file, LunarVim automatically installs the language server for lua, providing us with auto-completion and linting which makes working with the configuration file much easier.

Changing the Leader Key and Theme

By default LunarVim uses the spacebar as its leader key. I, however, prefer to use the comma key.
This is easily done by editing or adding the leader key entry:



lvim.leader = ","

The configuration contains a 'plugins' section that has been commented out by default. If we uncomment this section we gain access to a new color theme 'tokyonight'.

Uncomment the plugins section and modify the theme entry to use tokyonight:



lvim.colorscheme = "tokyonight"

After a restart we can see our new theme.

Installing Plugins

As you can probably tell, installing plugins can be as simple as adding the repository name to the lvim.plugins entry.
Let try adding a new plugin that will give us access to the dracula theme:



lvim.plugins = {
    {"folke/tokyonight.nvim"},
    {"dracula/vim"},
    {
      "folke/trouble.nvim",
      cmd = "TroubleToggle",
    },
}

If the plugins do not automatically install, we can install them manually by pressing colon(':') and running the command:



PackerInstall

Upon restart we can see our new theme in the list.

Reinstall Script

LunarVim has a tendency to break on occasion. A reinstallation seems to always fix these problems so I like to keep a script to handle the reinstallation and configuration file management.



#!/bin/bash

# Unstow dotfiles

echo 'Unstowing dotfiles...'

cd ~/.dotfiles && stow --delete lvim

# Uninstall

echo 'Running uninstall script...'

bash <(curl -s https://raw.githubusercontent.com/lunarvim/lunarvim/master/utils/installer/uninstall.sh)

# Install neovim

echo 'Installing neovim...'

bash <(curl -s https://raw.githubusercontent.com/LunarVim/LunarVim/rolling/utils/installer/install-neovim-from-release)

# Install lunarvim

echo 'Installing lunarvim...'

LV_BRANCH=rolling bash <(curl -s https://raw.githubusercontent.com/lunarvim/lunarvim/rolling/utils/installer/install.sh)

# Stow dotfiles

echo 'Stowing dotfiles...'

rm -rf ~/.config/lvim

cd ~/.dotfiles && stow lvim

Conclusion

LunarVim isn't the only project that maintains a sophisticated Neovim configuration. It is, however, actively developed and comes with many sane defaults which most people put into their Neovim configurations anyway.
It can be a great option for Neovim beginners or seasoned veterans who are tired of maintaining a fragile and frustrating configuration file.
LunarVim can also be used outside of development. This article was written using LunarVim with full spell-checking and grammar-checking support.

My LunarVim and other configurations can be found on my gitlab.

DEV Community: Chris Dawkins

Posta: Building a Social Blogging Backend with SurrealDB, Nix, and Nushell

What is Posta?

The Stack

SurrealDB

Nushell

Nix

A note about contributing to open source

Schema Design

Usage

New user

New Post

Edit Post

New Comment

Text Search

Testing

Conclusion

Resume-md: Manage your resume with GitHub and Markdown

What I built

siph / resume-md

Use markdown to generate a stylized resume in PDF and HTML and deploy a static site using GitHub Pages.

Resume-md

Usage

GitHub

About

Nix

GitHub Actions

GitHub Pages

Conclusion

Writing Polybar Modules in Nushell

Building the Module

Using the Module

Conclusion

Declare and version control you tmux sessions

Hi There! Have You Heard The Good News About Our Lord And Savior Nix?

Table of Contents

What is Nix?

Difference Between Nix and NixOS

System Management

User

Home Manager

Nixos-Generators

Server

Nixpkgs

Packaging Software

Flakes

Development Environment

Devshell

Learning Nix

Leverage Markdown and GitHub to Manage Your Resume with Resume-md

Resume-md

How To Use

Conclusion

Working with JSON in the command line with jq

What is jq?

Examples

Read Property

Arrays

Pipes

Filtering

Regex

Building JSON

Conclusion

Skylunch: API for aviators

Overview of My Submission

Submission Category:

Language Used

Link to Code

siph / skylunch

Api to find restaurants near airports.

Skylunch

How it works

Technologies

Data Storage and Access

Building a Tiling Window Manager with Rust and Penrose

What is a tiling-window manager?

Why Penrose?

Prerequisites

X11

Rust

What is `jq`?