Forem: Elliot DeNolf

White Label the Payload CMS Admin UI

Elliot DeNolf — Tue, 08 Feb 2022 07:00:00 +0000

Easily make Payload the perfect white labeled headless CMS. With Payload, you get complete control of the look and feel of the Admin Panel.

Across the Admin UI, the branding from Payload is minimal so that the focus stays where it should be—on your application. By updating the Payload branding, you can create a customized interface and your client (or team, or whoever will access your admin panel) will be greeted with a dynamic interface that is consistent with your application branding.

In this blog post, you will learn how to rebrand and white label the Payload admin panel for your application by modifying the following elements:

Favicon
Title
ogImage
Icon
Logo

Get Started

You can use your own Payload app or start a new one for this tutorial. If you haven't started a project yet, you can get set up easily by running npx create-payload-app in your terminal.

For more details on how to start an application, including how to do so from scratch, read the installation documentation.

Payload Config

Start by navigating to your base Payload config file in which all options for the Admin panel are defined.

Below is an example config file:

import { buildConfig } from 'payload/config';
import dotenv from 'dotenv';
import Page from './collections/Page';
import Media from './collections/Media';

dotenv.config();

export default buildConfig({
  serverURL: process.env.PAYLOAD_PUBLIC_SERVER_URL,
  collections: [
    Page,
    Media,
  ],
});

Admin Option

Next, add the admin option to your payload config file this can start as an empty object.

export default buildConfig({
  serverURL: process.env.PAYLOAD_PUBLIC_SERVER_URL,
  admin: {}, // Add this
  collections: [
    Page,
    Media,
  ],
});

Serving Images

We need to ensure the images are served somewhere they can be downloaded by the browser. We could have saved an absolute URL if the assets
are hosted somewhere. Instead of that we set relative paths to an assets folder for favicon.svg and logo.svg above;
we can serve them from the same express app as Payload is using. Create a directory called assets and save your images there.

Then in your server.js or wherever you have defined express routes, add the line that serves /assets with express.static:

import express from 'express';
import path from 'path';

const app = express();
// Add /assets
app.use('/assets', express.static(path.resolve(__dirname, '../assets')));

payload.init({
  secret: process.env.PAYLOAD_SECRET_KEY,
  mongoURL: process.env.MONGO_URL,
  express: app,
  license: process.env.PAYLOAD_LICENSE_KEY,
});

app.listen(process.env.PORT);

Note: Anything in that assets folder will be publicly available when your app is hosted online.

At this point, if we check out our app in the browser—the tab will display your updated favicon and title suffix.

To test that the ogImage has successfully updated, use the browser inspector to view the metadata or test your app through your social media of choice or a web developer tool e.g. Twitter’s Card Validator.

Custom Components

In addition to metadata, the admin option also takes custom components to override the default configuration.

The properties we are interested in for rebranding the admin panel are:

graphics.Logo: Image component to be displayed as the logo on the Sign Up / Login view.

graphics.Icon: Image component displayed above the Nav in the admin panel, often a condensed version of a full logo.

Now let's set up these custom components:

Add components and open an object
Within components, add the graphics property and open another object
Now we can point to the relevant files for the Logo and Icon

import Logo from './graphics/Logo';
import Icon from './graphics/Icon';

dotenv.config();

export default buildConfig({
  serverURL: process.env.PAYLOAD_PUBLIC_SERVER_URL,
  admin: {
     meta: {
       titleSuffix: '- Custom Title',
       favicon: '/favicon.svg',
       ogImage: '/logo.svg',
     },
     // Add components
     components: {
       graphics: {
         Logo,
         Icon,
       },
     },
  },
  collections: [
    Page,
    Media,
  ],
});

These graphics need to be React components that can render whatever you'd like. They could render img tags or full React SVGs. In this example, we're going to include images, css and other html too.

import React from 'react';
import './logo.scss';

export const Logo = () => (
  <div className="logo">
    <img
      src="/assets/logo.png"
      alt="TRBL Design Logo"
    />
  </div>
);

Optionally we can include some styling too.

.logo {
  img {
    max-height: 200px;
    margin: auto;
  }

  h1 {
    margin: 3rem auto;
    text-align: center;
  }
}

Final step, let’s check out the new logo and icons.

Summary

There you have it! With around 10 lines of code you can brand the admin panel, update metadata and add custom components to effectively white label the admin panel for your clients or users.

Payload gives you the freedom and control to customize other aspects too, like the swapping out the Dashboard or creating custom inputs, to learn more about the admin panel and custom components—check out the pages below.

Questions or Comments?

Join us on GitHub discussions.

Build Your Own Role-Based Access Control in Payload

Elliot DeNolf — Wed, 14 Jul 2021 12:55:02 +0000

Payload comes with open-ended access control. You can define whatever type of pattern that you can dream up, and best of all—it's all done with simple JavaScript.

A common pattern is Role-Based Access Control. Here, we'll walk you through how to create your own RBAC pattern on both the collection-level and field-level.

In more detail, here are the pieces that we will be building:

Users collection with role field
Orders collection
- A beforeChange hook to save which user created the order to a createdBy field
- Access Control functions to restrict Admin Panel access to admin roles or the creator of the order
- admin-only field level access

Initialize Project

We'll be using create-payload-app to build out the initial project.

Run npx create-payload-app payload-rbac
Select javascript for language
Select blank for our template
Follow all other prompts

This will give us a simple project with a Payload config and Users collection. The structure of the project will be:

├─ payload.config.js
└─ collections/
  └─ Users.js
  └─ Orders.js

Modify Users Collection

First, we will add the role field to our Users collection with 2 options: admin and user.

const Users = {
  slug: 'users',
  auth: true,
  admin: {
    useAsTitle: 'email',
  },
  fields: [
    {
      name: 'role',
      type: 'select',
      options: [
        { label: 'Admin', value: 'admin' },
        { label: 'User', value: 'user' },
      ],
      required: true,
      defaultValue: 'user',
    },
  ],
};

export default Users;

Create Orders Collection

Next, we will create a new Orders.js collection in our collections/ directory and scaffold out basic fields and values - including the createdBy relationship to the user.

const Orders = {
  slug: 'orders',
  fields: [
    {
      name: 'items',
      type: 'array',
      fields: [
        {
          name: 'item',
          type: 'text',
        }
      ]
    },
    {
      name: 'createdBy',
      type: 'relationship',
      relationTo: 'users',
      access: {
        update: () => false,
      },
      admin: {
        readOnly: true,
        position: 'sidebar',
        condition: data => Boolean(data?.createdBy)
      },
    },
  ]
}

export default Orders;

The Orders collection has an array field for items and a createdBy field which is a relationship to our Users collection. The createdBy field will feature a strict update access control function so that it can never be changed.

Notice we also have a condition function under the createdBy field's access. This will hide createdBy until it has a value.

Set the `createdBy` Attribute Using a Hook

Next, we'll add a hook that will run before any order is created. This is done by adding a beforeChange hook to our collection definition.

const Orders = {
  slug: 'orders',
  fields: [
    // Collapsed
  ],
  hooks: {
    beforeChange: [
      ({ req, operation, data }) => {
        if (operation === 'create') {
          if (req.user) {
            data.createdBy = req.user.id;
            return data;
          }
        }
      },
    ],
  },
}

The logic in this hook sets the createdBy field to be the current user's id value, only if it is on a create operation. This will create a relationship between an order and the user who created it.

Access Control

Next, the access control for the collection can be defined. Payload's access control is based on functions. An access control function returns either a boolean value to allow/disallow access or it returns a query constraint that filters the data.

We want our function to handle a few scenarios:

A user has the 'admin' role - access all orders
A user created the order - allow access to only those orders
Any other user - disallow access

const isAdminOrCreatedBy = ({ req: { user } }) => {
  // Scenario #1 - Check if user has the 'admin' role
  if (user && user.role === 'admin') {
    return true;
  }

  // Scenario #2 - Allow only documents with the current user set to the 'createdBy' field
  if (user) {

    // Will return access for only documents that were created by the current user
    return {
      createdBy: {
        equals: user.id,
      },
    };
  }

  // Scenario #3 - Disallow all others
  return false;
};

Once defined, this function is added to the access property of the collection definition:

const Orders = {
  slug: 'orders',
  fields: [
    // Collapsed
  ],
  access: {
    read: isAdminOrCreatedBy,
    update: isAdminOrCreatedBy,
    delete: isAdminOrCreatedBy,
  },
  hooks: {
    // Collapsed
  },
}

With this function added to the read, update, and delete access properties, the function will run whenever these operations are attempted on the collection.

Note: Access functions default to requiring a logged-in user. This is why create does not need to be defined for this example, since we want any logged in user to be able to create an order.

Put It All Together

The last step is to add the collection to our payload.config.js

import { buildConfig } from 'payload/config';
import Orders from './collections/Orders';
import Users from './collections/Users';

export default buildConfig({
  serverURL: 'http://localhost:3000',
  admin: {
    user: Users.slug,
  },
  collections: [
    Users,
    Orders,
  ],
});

Let's verify the functionality:

Start up the project by running npm run dev or yarn dev and navigate to http://localhost:3000/admin

Create your initial user with the admin role.

Create an Order with the admin user.

Create an additional user with the user role by navigating to the Users collection, selecting Create New, entering an email/password, then saving.

Log out of your admin user by selecting the icon in the bottom left, then log in with the second user.

You'll notice if we go to the Orders collection, no Orders will be shown. This indicates that the access control is working properly.

Create another Order. Note that the current user will be saved to Created By in the sidebar.

Navigate back to Orders list on the dashboard. There will only be the single order created by the current user.

Log out, then back in with your admin user. You should be able to see the original Order as well as the Order created by the second user.

Field Level Access Control

With everything working at the collection level, we can carry the concepts further and see how they can be applied at the field level. Suppose we wanted to add a paymentID field only for Admin users. Create an isAdmin function that checks the role as we did earlier.

const isAdmin = ({ req: { user } }) => (user && user.role === 'admin');

Add a new field to Orders and set create, read or update access calls to use the isAdmin function.

const Orders = {
  slug: 'orders',
  fields: [
    // Collapsed
    {
      name: 'paymentId',
      type: 'text',
      access: {
        create: isAdmin,
        read: isAdmin,
        update: isAdmin,
      },
    }
  ],
  // Collapsed
}

The new paymentID field is not available to the users even on one's own Order. Field level access controls allow for greater granularity over document level access for Collections and Globals. This shows how easy it is to manage exact permissions throughout the admin UI, GraphQL and REST endpoints; it even works when querying relationships to keep data secure.

What Other Improvements Can Be Made?

Now that we have a basic example working. What are some ways that this could be improved?

Ideally, we'd want to use both the hook and the access control function across multiple collections in our application. Since it's just JavaScript, we can extract each of these functions into their own file for re-use.
Add additional roles, such as an editor role which allows reading and editing, but disallows creating. This all can be customized specifically to your needs.

Questions or Comments? Join us on GitHub Discussions

I hope you enjoyed the introduction to doing role-based access control with Payload!

Come join the Payload discussions on GitHub.

Build .NET 5 Applications with GitHub Actions

Elliot DeNolf — Wed, 23 Dec 2020 00:00:00 +0000

This article will go through setting up GitHub Actions to build and test a .NET 5 application.

Create Basic Application

First, let’s build out our basic application and test suite using the dotnet CLI. Create a new directory for your project and go through the following commands:

mkdir MyApp MyApp.Tests
cd MyApp
dotnet new webapi
cd ../MyApp.Tests
dotnet new xunit
cd ..
dotnet new sln
dotnet sln add **/*.csproj

We’ve now built out a solution with a web API and test suite to use in our Workflow.

Before we move forward, here is our simplified project structure:

.
|-- MyApp
| |-- MyApp.csproj
| |-- Program.cs
| `-- Startup.cs
|-- MyApp.Tests
| |-- MyApp.Tests.csproj
| `-- UnitTest1.cs
`-- MyApp.sln

Create Workflow

GitHub Actions is driven by having workflow definitions in the .github/workflows directory. Create these 2 directories and add a file named ci.yml.

The first thing we will add to our ci.yml will be a name and an on trigger. This simply gives our workflow a name and also defines when the workflow should run - when we push to the repository.

name: .NET 5 CI
on: [push]

Next, we define our jobs section. We will only be adding a single job that will have multiple steps. Add the following to our ci.yml which will simply define our job and what OS it will run on.

jobs:
  build:
    runs-on: ubuntu-latest
    name: .NET 5 Application

The first step of our job will be to configure .NET with our desired version - .NET 5 in our case

jobs:
  build:
    runs-on: ubuntu-latest
    name: .NET 5 Application
    steps:
      - uses: actions/checkout@v2
      - name: Setup dotnet
        uses: actions/setup-dotnet@v1
        with:
          dotnet-version: '5.0.101' # Check for latest at link below

NOTE: The dotnet-version used is the latest from the .NET 5 Download page. Be sure to check the latest version available and swap that in. Wildcarding the version like 5.x should be supported in the near future.

Now that .NET is configured and makes the dotnet cli available to our workflow, we will add steps for dotnet build and dotnet test.

Let’s add those. The complete ci.yml should look like this:

name: .NET 5 CI
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    name: .NET 5 Application
    steps:
      - uses: actions/checkout@v2
      - name: Setup dotnet
        uses: actions/setup-dotnet@v1
        with:
          dotnet-version: '5.0.101' # Check for latest at link at .NET 5 download page
      - run: dotnet build
      - run: dotnet test

If we add commit this file, push, and navigate to the Actions section of our repository, we will see a new workflow run that goes through all of the steps.

Bootstrap your Dotfiles with dotbot

Elliot DeNolf — Mon, 13 Jul 2020 00:00:00 +0000

A customized set of dotfiles can vastly increase your command-line productivity and happiness. Having your dotfiles in a repo allows you to take your configuration anywhere. In this tutorial, we'll be setting up a dotfiles repository and bootstrapping it using dotbot.

Why Dotbot?

While it could be tempting for some to script your dotfiles configuration and installation yourself, I would advise against going this route. I previously went this route, but I would constantly run into edge-cases leading to constant modification of the scripts. With a framework, most of the use-cases have been thought of, so it is very low friction in comparison.

On investigating a number of tools out there, dotbot's features set it apart from the others:

Single configuration file
Single command to install on a new machine via symbolic links
Can be added as a git submodule
Python is the only dependency (standard for almost all distros)

Getting Started

The first step is to get a git repository started and add dotbot as a submodule

# Create project directory
> mkdir dotfiles
> cd dotfiles

# Initialize Repository
> git init
> git submodule add https://github.com/anishathalye/dotbot
> cp dotbot/tools/git-submodule/install .
> touch install.config.yaml

So now we have a few things set up:

New git repository
Dotbot added as a submodule
Dotbot's install script copied to the project root
A blank configuration file

Configuration

Next, we'll start modifying our config file. Here is a starting point:

- defaults:
    link:
      relink: true

- clean: ['~']

- link:
    ~/.bashrc: bashrc
    ~/.zshrc: zshrc
    ~/.vimrc: vimrc

- shell:
  - [git submodule update --init --recursive, Installing submodules]

Let's go through each section to see what it does

Defaults

Defaults controls what action will be taken for everything in the link section. relink removes the old target if it is a symlink. There are additional options that may be worth looking at in the documentation

Clean

This simply defines what directory should be inspected for dead links. Dead links are automatically removed.

Link

This is where most of your modifications will take place. Here we define where we want the symlink to be once linked, and what file should be linked there. In the above example, we have 3 files that commonly contain customizations.

Shell

This section contains any raw shell commands that you'd like to run upon running your install script. In this case, it installs any submodules.

Move files into Repository

Next, we move the files we want to link into our repository. Assuming you want the 3 files specified from above, we can run the following commands to move them in.

> cp ~/.vimrc ./vimrc
> cp ~/.zshrc ./zshrc
> cp ~/.bashrc ./bashrc

Run Install Script

We can test out if everything works properly by running ./install within our repository. If all is configured properly, you should see something like the following:

> ./install
All targets have been cleaned
Creating link ~/.bashrc -> ~/.dotfiles/bashrc
Creating link ~/.zshrc -> ~/.dotfiles/zshrc
Creating link ~/.vimrc -> ~/.dotfiles/vimrc
All links have been set up
Installing submodules [git submodule update --init --recursive]
All commands have been executed

==> All tasks executed successfully

Once you are satisfied with how you dotfiles install, be sure to commit your changes and push to a remote repository.

> git add --all
> git remote add origin git@github.com:username/dotfiles.git
> git push -u origin master

Use on Multiple Machines

Now that you have a basic dotfiles repository set up, you can push this to a public repository in order to use on multiple machines. On any machine, you can now simply run the following commands to install your dotfiles:

> git clone git@github.com:username/dotfiles.git --recursive
> cd dotfiles && ./install

Any new changes can be retrieved from the repository and installed using the following commands:

> git pull
> ./install

Summary

You can now easily maintain your dotfiles in a git repository and share them between your environments.

Here is my personal dotfiles repository that uses dotbot. There are many other places to draw dotfiles inspiration from such as GitHub Does Dotfiles and other dotbot users.

Easily Rerun EC2 UserData

Elliot DeNolf — Mon, 29 Jun 2020 00:00:00 +0000

EC2 UserData code blocks only run when an EC2 starts up for the first time by default. Rerunning this code can be useful for troubleshooting purposes. However, the way to do this is not very straight forward. Let's go through how to view, verify, and execute your EC2's UserData.

First, we must log into our EC2 using SSH and our .pem file.

> ssh -i "my-cert.pem" ec2-user@my.machine.ip

This article will not go into the details of how to SSH into a machine, you can learn how to do this from the AWS Documentation.

Next, we must elevate to the root user.

> sudo -i

An EC2's UserData can be accessed at the url: http://instance-data/latest/user-data, so we can use curl to redirect this to a file in order to inspect it.

> curl http://instance-data/latest/user-data > user-data.sh

We can then inspect the file using cat or vim.

> cat ./user-data.sh

We can then modify the permissions and execute it.

> chmod +x user-data.sh
> ./user-data.sh

Other Variations

We can run the script in one single command if we don't want to inspect it first by piping it directly.

> curl http://instance-data/latest/user-data | sh

Another option is if you'd like to see each line written to STDOUT as it runs, we can enable this by adding set -ex to the top of our user-data.sh script before executing it.

Polyglot Version Management with asdf

Elliot DeNolf — Thu, 25 Jun 2020 00:00:00 +0000

Originally published on my blog at elliotdenolf.com

Dabbling in multiple programming languages can be a lot of fun. However, because each language tends to have its own version manager, remembering each version manager's commands can get a little cumbersome. This is why the idea of having a single version manager for all of your languages is very intriguing. Asdf is a version manager that aims to do that. It supports a large number of languages, all with only one set of commands to remember.

Let's get it installed, add a language plugin, then activate the desired language version.

Installation

Installation is performed using either Homebrew on macOS or Git on Linux.

# macOS
> brew install asdf
# Linux
> git clone https://github.com/asdf-vm/asdf.git ~/.asdf

You must then source the script by adding the following line to your ~/.zshrc, ~/.bashrc, or ~/.bash_profile.

. ~/.asdf/asdf.sh

See the latest documentation if more detail is needed.

Usage

Asdf has the concept of "plugins" for each supported language. We need to install a plugin for any language we want to use.

First, let's list all available plugins using asdf plugin-list-all.

> asdf plugin-list-all
golang          https://github.com/kennyp/asdf-golang.git
nodejs          https://github.com/asdf-vm/asdf-nodejs.git
python          https://github.com/danhper/asdf-python.git
ruby            https://github.com/asdf-vm/asdf-ruby.git
# many more...

From the list, let's add the Node.js plugin.

> asdf plugin-add nodejs

Once the plugin is added, we can list all versions available to us.

> asdf list-all nodejs
12.16.0
12.16.1
12.16.2
12.16.3
12.17.0
12.18.0
12.18.1
# many more...

Any version from the list can be installed, we'll install the latest LTS.

> asdf install nodejs 12.18.1

Once installed, we declare this version as the one we'd like to use globally on our system.

> asdf global nodejs 12.18.1

If you need to run a specific version only for a single project, we can do that using the asdf local command.

> cd node-10-project
> asdf local nodejs 10.21.0

This will create a file named .tool-versions that specifies which version should be used within the current project. Asdf will automatically detect and use that version if it is installed.

The above steps can be repeated for any language we'd like.

All plugins and versions installed can be viewed with the asdf list command.

> asdf list
golang
  1.14
  1.15beta1
nodejs
  10.20.0
  12.18.1
python
  3.8.2
  3.10-dev
ruby
  2.7.0
  2.8.0-dev

Summary

Asdf is a very powerful tool that can replace aany number of version managers. I'd highly recommend using it if you use more than a couple languages on your system and have a need to switch between versions. Head on over to their documentation if you'd like to learn more.

My Tech Podcasts: Summer 2020 Edition

Elliot DeNolf — Tue, 23 Jun 2020 00:00:00 +0000

Tech podcasts are a great way to stay on top of everything going on in the software development industry. I’ve been listening to podcasts for many years, and my list evolves over time. Here is my current list for Summer 2020:

Software Engineering Daily

This podcast is in the 1 on 1 interview format, and the guests are usually either very prominent figures in the community or someone who has been working on cutting edge technology. This podcast also serves as a way to know what is trending in the enterprise software community.

Indie Hackers

This podcast goes into the entrepreneurial aspect of software development which can be refreshing. It’s very cool to see how each creator markets and monetizes their software product or service.

The ChangeLog

This podcast is similar to Software Engineering Daily in a lot of ways, but they focus more on Open Source instead of enterprise technologies.

Full Stack Radio

This is a very web app and JavaScript focused podcast. It involves a lot of interviews about the latest JavaScript frameworks with their creators or advocates.

Syntax.fm

I really like listening to Wes and Scott. They have a great rapport which makes this podcast easy listening. Some of the topics tend to be a little too web development focused or too beginner-friendly for my taste. However, I do like looking at the title of each podcast to see if it’s worth tuning in.

Backup and Restore Visual Studio Code Extensions from the Command Line

Elliot DeNolf — Mon, 22 Jun 2020 00:00:00 +0000

Originally posted on my blog at elliotdenolf.com

I maintain my own dotfiles to be able to have identical setups between my work and personal machines. My Visual Studio Code configuration is one piece of those. While there is an extension out there that does extension syncing, I didn't find them ideal for my use-case as it also did a settings sync.

Backup Extensions

Let's output our list of extensions to a file.

> code --list-extensions > extensions.txt

The file content will be similar to the following:

donjayamanne.githistory
eamodio.gitlens
johnpapa.vscode-peacock
ms-azuretools.vscode-docker
yzhang.markdown-all-in-one

Restore Extensions

Once we have our file listing our extensions, we can restore our extensions.

> cat extensions.txt | xargs -L 1 code --install-extension

This line performs the code --install-extension command for every line in your file.

Use with a Script

To make these commands easier to use, we can use a script that wraps the code command. The following script will add code save-ext and code install-ext as commands. Any other standard command will simply be passed through.

#!/usr/bin/env bash

if command -v code >/dev/null 2>&1; then
  code() {
    case "$1" in
    save-ext)
      echo "Saving code extensions..."
      code --list-extensions > ~/.dotfiles/vscode/extensions.txt
      ;;
    install-ext)
      echo "Installing code extensions..."
      cat ~/.dotfiles/vscode/extensions.txt | xargs -L 1 code --install-extension
      ;;
    *)
      command code "$@"
      ;;
    esac
  }
fi

To use this script, modify the extensions.txt file path and also add the script to your PATH.

code save-ext will output your extensions to file
code install-ext will install them from file

I'd recommend saving this file to your personal dotfiles to share between your dev environments. Here are mine.

C# Scripting using dotnet-script

Elliot DeNolf — Mon, 15 Jun 2020 00:00:00 +0000

Originally posted on my blog at elliotdenolf.com

C# is an extremely powerful language but for small, simple tasks it tends to be a bit overkill because of the boilerplate required. dotnet-script is a project that aims to alleviate that friction. It allows C# code to be run as a single script file. No Main method, no .csproj, and transparent compilation.

Let's create a simple "Hello World" script as well as a more complex script that uses a NuGet package.

Installation

To install dotnet-script, we use the dotnet cli to install it globally:

> dotnet tool install -g dotnet-script
# Optionally include specific version
> dotnet tool install -g dotnet-script --version 0.53.0

The latest version will be listed at nuget.org if you wish to use a specific one.

Create Script

dotnet-script comes with an init command to generate a simple script. Let's create a directory and run that.

> mkdir dotnet-script-test
> cd dotnet-script-test
> dotnet script init

The init script will generate 2 files: main.csx and omnisharp.json

omnisharp.json contains script settings like target framework and allowing nuget references
main.csx is scaffolded to contain a simple, functioning Hello World example

The contents of our main.csx will be:

#!/usr/bin/env dotnet-script

Console.WriteLine("Hello world!");

First, test that your script is functioning by running ./main.csx on your command line. You should see the Hello World! output. Windows machines may need to run the script using dotnet script main.csx since the "shebang" line may not be included.

Use NuGet Package

From here, we can make something a bit more complex. Let's pull in a nuget package and use it.

In a dotnet script file, nuget packages are pulled in using the #r directive. In this example, we'll pull in the Bogus nuget package in order to generate some realistic first and last names. If we browse nuget.org to find the Bogus package, the latest version is 29.0.2 at the time of writing. Below is how we pull in the package and add a using statement to make use of it.

#!/usr/bin/env dotnet-script

#r "nuget: Bogus, 29.0.2"

using Bogus;

From here, let's create a simple Person class with FirstName and LastName properties.

public class Person
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
}

Let's create a person with a random name and output them using the following code:

var peopleGenerator = new Faker<Person>()
    .RuleFor(o => o.FirstName, f => f.Name.FirstName())
    .RuleFor(o => o.LastName, f => f.Name.LastName());

var person = peopleGenerator.Generate();
Console.WriteLine($"Hello, {person.FirstName} {person.LastName}");

Run this with ./main.csx on the command line. You should see something similar to this output.

> ./main.csx
Hello, Darian Bartell

Overall, I think using dotnet-script is an easy way to have small, concise C# scripts without the overhead of compiling them into command-line applications and having to maintain .csproj files.

Chromebook For Development - 1 Year In

Elliot DeNolf — Thu, 25 Jul 2019 00:00:00 +0000

Originally posted on my blog at https://elliotdenolf.com/posts/chromebook-for-development-1-year-in/

With the advent of "Linux on Chromebooks", using a Chromebook for development has become enticing in many ways. They are lightweight, fast to boot, have great battery life, and require no maintenance. When I heard that Linux applications would now be supported out-of-the-box, starting with the Pixelbook, I jumped at the opportunity. I've been doing development on my Pixelbook since June 2018. Below, I summarize my experience so far.

Enabling Linux

Anyone that has installed a Linux distro on a laptop knows that you can often run into issues with driver support. Using a Chromebook completely removes any issues related to doing this. It is a simple toggle in settings, wait for the download, then restart. There is now an application called "Terminal" that gives you access to a full Debian version of Linux.

Main applications

Konsole - The default "Terminal" application works fine for simple use-cases. However, most developers will want additional features like tabs, color schemes, etc. There are a handful of options out there. I found Konsole's mix of features to be the sweet spot for me.
Terminal tools - I have not had any issues running any terminal tool. Anything that Debian will run, runs as expected. I work extensively with the following:
- Node and TypeScript (tsc)
- .NET Core (dotnet)
- Crystal
Docker. Though this is terminal-based, I thought it deserved a specific call-out. Initially, I had issues with getting the Docker daemon working properly. I'm happy to say those issues were ironed out late-Summer of 2018. Since then, I've had no issues running a few containers at a time and doing normal Docker tasks.
VS Code - This is the jackknife of the editor world. It can be used to edit anything, and there is almost always is an extension for the functionality you are looking for. I was concerned at first about the performance because it is an electron-based application, but I have not run into any issues.
Other applications I make use of are WebStorm, Postman, Slack, Robo3t

It is worth noting that my Pixelbook runs an i5 with 8gb of RAM, which is considered very high specs compared to most other Chromebooks in the market.

Limitations

No OS-level modifications - Chrome OS does not allow custom global shortcuts or using a different launcher. This was one area that I struggled with since I typically make heavy use of tools like Alfred, Karabiner, and AutoHotkey. These applications provide an extra level of control and automation that just cannot be rivaled on a Chromebook. The OS is very locked down, and not having access to tools like these is a side-effect of that.
Desktop Environment - Chrome OS provides a shortcut and gesture to give you an overview of all open windows. It also provides basic splitting of windows left and right. However, the shortcut to split windows is not recognized when a Linux application is in focus, so I have to use the mouse to snap the window to the side to split it. "Virtual Desks" are scheduled to roll out to the Stable channel within the next few weeks. A feature I am very excited about and is a move in the right direction for the desktop environment in Chrome OS.
Graphics applications. GPU support for Linux is just being rolled out. However, until now any applications that would take advantage of a graphics card are very anemic.

Overall, if your development workflow uses a Linux-based OS, a terminal, and (optionally) an editor, I feel you may be genuinely surprised how well a Chromebook will work as a development machine.

Build .NET Core Applications using GitLab CI

Elliot DeNolf — Mon, 01 Apr 2019 00:00:00 +0000

Originally posted on my blog at https://elliotdenolf.com/posts/build-net-core-applications-using-gitlab-ci

Updated for .NET 5

GitLab CI has the ability to utilize any docker container in order to build and deploy an application. This makes it an extremely flexible tool. This article will go through building out a GitLab CI pipeline for a .NET Core application.

Create Basic Application

First, let’s build out our basic application and test suite using the dotnet CLI. Create a new directory for your project and go through the following commands:

mkdir MyApp MyApp.Tests
cd MyApp
dotnet new webapi
cd ../MyApp.Tests
dotnet new nunit
cd ..
dotnet new sln
dotnet sln add **/*.csproj

We’ve now built out a basic application and test suite to use in our pipeline.

Before we move forward, here is our simplified project structure:

.
|-- MyApp
| |-- MyApp.csproj
| |-- Program.cs
| `-- Startup.cs
|-- MyApp.Tests
| |-- MyApp.Tests.csproj
| `-- UnitTest1.cs
`-- MyApp.sln

Create Pipeline

GitLab CI is driven by having a .gitlab-ci.yml file at the root of the project. Create this file now. The first thing we will put into this file is our base image

image: mcr.microsoft.com/dotnet/sdk:5.0

This is the official dotnet core image from Microsoft. It includes the latest .NET Core SDK, which provides everything needed to build out an application. A container running this image will be where our scripts will run and application code cloned into. The version can also be changed to build previous dotnet versions.

Next, we define our stages. We will be building out 3 distinct stages: build, test, and release. Those are added by adding this block:

stages:
  - build
  - test
  - release

Now that our stages are set up, we can add build steps and associate them with our defined stages. We just happen to want a single step for each of the build and test stages.

Let’s add the build step that will build via the dotnet CLI:

build:
  stage: build
  script:
    - dotnet build

The top-level value can be named anything you’d like. If you only have one step per stage, keeping them the same name keeps things simple. However, the stage value must specify one of the listed stages from above. This is how GitLab CI knows what stage to run this step on.

If the build stage succeeds, we want our unit tests to run. The following block will run the test command via the dotnet CLI:

test:
  stage: test
  script:
    - dotnet test

The release step will be more complex than the previous because we will be using the dotnet publish command along with capturing the generated artifacts. This is the release block:

release:
  stage: release
  only:
    - master
  artifacts:
    paths:
      - publish/
  script:
    - dotnet publish -c Release -o ../publish MyApp/MyApp.csproj

Let’s break down each piece of this step.

The only section specifies that this step will only run on our master branch. This is to avoid generating artifacts for feature branches
The artifacts path points to our intended output directory
The dotnet publish command outputs into a publish directory at our project root. Make note of the ../ before publish as the dotnet publish command outputs relative to the csproj file that is specified, so we want the artifacts to be output one directory up at the root.

Our full .gitlab-ci.yml file should now look like this:

image : mcr.microsoft.com/dotnet/sdk:5.0

stages:
  - build
  - test
  - release

build:
  stage: build
  script:
    - dotnet build

test:
  stage: test
  script:
    - dotnet test

release:
  stage: release
  only:
    - master
  artifacts:
    paths:
      - publish/
  script:
    - dotnet publish -c Release -o ../publish MyApp/MyApp.csproj

If we commit this code and navigate to CI/CD -> Pipelines in our GitLab repository, we will be able to see a pipeline that ran for the commit. If successful, each step will have a green check and artifacts will be available for download. If there was a failure, it will be a red X that can be clicked on to see more detail.

Additional steps can be added beyond what I’ve provided, but they would differ greatly based upon your environment. This application could easily be put into a Docker image and pushed either to the GitLab image registry or your Kubernetes cluster. However, that would warrant an entire article on its own. You now have a basic CI pipeline for your .NET Core application!

Cucumber.js with TypeScript

Elliot DeNolf — Fri, 29 Mar 2019 00:00:00 +0000

Originally posted on my blog at https://elliotdenolf.com/posts/cucumberjs-with-typescript

Cucumber.js is the JavaScript implementation of Cucumber. The main benefit of writing automated tests for Cucumber is that they are written in plain English, so any non-technical person can read the scenarios and know what is being tested. This is extremely powerful in larger organizations because it allows developers, testers, and business stakeholders to better communicate and collaborate.

This post will go through setting up a basic Cucumber.js suite using TypeScript and cucumber-tsflow. Cucumber-tsflow is a package that will allow us to take advantage of TypeScript’s decorators, which make for clearer step definition code.

The first step will be installing our dependencies:

npm i -D cucumber cucumber-tsflow cucumber-pretty ts-node typescript chai
npm i -D @types/cucumber @types/chai

experimentalDecorators must also be set to true in your tsconfig.json in order for the decorators to compile properly.

The two main components for cucumber tests are feature files and step definitions. Let’s start out by creating a features directory then creating a file named bank-account.feature inside it. Our example will be testing the basic functionality of a bank account.

# features/bank-account.feature
Feature: Bank Account

  Scenario: Stores money
    Given A bank account with starting balance of $100
    When $100 is deposited
    Then The bank account balance should be $200

This defines a single scenario for depositing money into a bank account. Next, we will create a directory named step-definitions and create a file named bank-account.steps.ts within it.

import { binding, given, then, when} from 'cucumber-tsflow';
import { assert } from 'chai';

@binding()
export class BankAccountSteps {
  private accountBalance: number = 0;

  @given(/A bank account with starting balance of \$(\d*)/)
  public givenAnAccountWithStartingBalance(amount: number) {
    this.accountBalance = amount;
  }

  @when(/\$(\d*) is deposited/)
  public deposit(amount: number) {
    this.accountBalance = Number(this.accountBalance) + Number(amount);
  }

  @then(/The bank account balance should be \$(\d*)/)
  public accountBalanceShouldEqual(expectedAmount: number) {
    assert.equal(this.accountBalance, expectedAmount);
  }
}

We are utilizing the cucumber-tsflow package which exposes some very useful decorators for our Given, When, and Then steps. The code within each step is fairly simple. The Given step initializes the accountBalance, the When step adds to the balance, and the Then step asserts its value.

Some specific things to note: this file exports a single class which has the @binding() decorator on it which is required for cucumber-tsflow to pick up the steps. Each step definition must also have a @given, @when or @then decorator on it. These decorators take a regular expression as a parameter which is how the lines in the feature file map to the code. Also, make note that there are capture groups in the expressions to capture values from the text and are subsequently passed as parameters to the function.

Cucumber is run using the cucumber-js command with a series of command-line switches. However, this can optionally be put into a cucumber.js file at the root of the project. Create a cucumber.js file at the root of the project with the following contents:

// cucumber.js
let common = [
  'features/**/*.feature', // Specify our feature files
  '--require-module ts-node/register', // Load TypeScript module
  '--require step-definitions/**/*.ts', // Load step definitions
  '--format progress-bar', // Load custom formatter
  '--format node_modules/cucumber-pretty' // Load custom formatter
].join(' ');

module.exports = {
  default: common
};

Putting the configuration in this file allows us to simply pass the profile name to cucumber-js (default in our case) instead of a long list of arguments. This file is building out all of the command line arguments, joining them, then exporting them under a named property. Let’s add an npm script to our package.json, so we can easily run it.

// package.json
{
  // ...
  "scripts": {
    "test": "./node_modules/.bin/cucumber-js -p default"
  },
  // ...
}

The structure of your project should now look like this:

.
|-- cucumber.js
|-- features
| `-- bank-account.feature
|-- package.json
|-- step-definitions
| `-- bank-account.steps.ts
`-- tsconfig.json

Now when we run npm test, cucumber-js inside of our node_modules will be executed with the -p default switch denoting the default profile exported from our cucumber.js file we created earlier.

The output should be something similar to this:

Feature: Bank Account

  Scenario: Stores money
    Given A bank account with starting balance of $100
    When $100 is deposited
    Then The bank account balance should be $200

1 scenario (1 passed)
3 steps (3 passed)
0m00.004s

That’s it! You’re up and going with Cucumber and TypeScript!

Forem: Elliot DeNolf

White Label the Payload CMS Admin UI

Get Started

Payload Config

Admin Option

Meta

Serving Images

Custom Components

Summary

Read More

Questions or Comments?

Build Your Own Role-Based Access Control in Payload

Initialize Project

Modify Users Collection

Create Orders Collection

Set the createdBy Attribute Using a Hook

Access Control

Put It All Together

Field Level Access Control

What Other Improvements Can Be Made?

Questions or Comments? Join us on GitHub Discussions

Further Reading

Build .NET 5 Applications with GitHub Actions

Create Basic Application

Create Workflow

Links

Bootstrap your Dotfiles with dotbot

Why Dotbot?

Getting Started

Configuration

Defaults

Clean

Link

Shell

Move files into Repository

Run Install Script

Use on Multiple Machines

Summary

Easily Rerun EC2 UserData

Other Variations

Links

Polyglot Version Management with asdf

Installation

Usage

Summary

Links

My Tech Podcasts: Summer 2020 Edition

Software Engineering Daily

Indie Hackers

The ChangeLog

Full Stack Radio

Syntax.fm

Backup and Restore Visual Studio Code Extensions from the Command Line

Backup Extensions

Restore Extensions

Use with a Script

Links

C# Scripting using dotnet-script

Installation

Create Script

Use NuGet Package

Links

Chromebook For Development - 1 Year In

Enabling Linux

Main applications

Limitations

Build .NET Core Applications using GitLab CI

Create Basic Application

Create Pipeline

Links

Cucumber.js with TypeScript

Links

Set the `createdBy` Attribute Using a Hook