Alexander Zeitler

Farewell...

2015-01-17T22:00:00Z

The title of this post might sound a bit scenic, but 2014 indeed has been a year of goodbys for me - at least regarding software development. As almost every leave also is a fresh start, lots of things have changed.

So lets say farewell to...

... .NET only software development

While contributing to "Pro ASP.NET Web API", doing talks and projects on ASP.NET Web API in 2012 and 2013 by persuasion, 2014 has become the year where I decided to gain broader knowledge by practice in the non-Microsoft space.

This means digging into Linux, Node.js and MongoDb and all that things like Gulp, Yeoman, Docker and ...you name it.

I also nosed around Scala, Go and Erlang, but in the end, I stick with Node.js and it's friends.

Things that felt bumpy (especcially because of Windows, e.g. CMD vs bash, Docker vs. ...?) in the .NET world, worked like a charm on the new stack and allowed me to purge my whole software development and deployment process.

Also the huge open source momentum in the Node.js ecosystem deeply impressed me.

On the other hand, in 2014, the .NET stack also has moved forward and Node.js not always is the promised land. The biggest gain for ages has been open sourcing the .NET framework and making it a real cross platform development environment.

As a .NET developer since the early days, I surely won't leave the .NET ecosystem in the near future, but there may be requirements where I or my customers will prefer the Node.js environment in the future.

... blog.alexonasp.net

When you're reading these lines, my old blog "Alex on ASP.NET" which has been around since 2003, is gone. As aforementioned, I'm no longer developing solely in the .NET space and thus my blog needs to be as open as I am.

... BlogEngine.NET

"Alex on ASP.NET" in it's early days has been running on "dasBlog" which has been replaced by SubText later on. Since 2006 it has been running on BlogEngine.NET.

As blog posts after being published, almost never are modified, running a database backed blog engine doesn't make sence to me any longer.

Because of this, I migrated my old blog to Wintersmith, a static site generator based on Node.js. It is now hosted on the DigitalOcean cloud platform and deployment is done using git.

I'll cover this in a upcoming post for everyone who's interested in that topic.

MongoDB development environment journal size management using mongoctl

2015-01-26T21:00:00Z

On a developer machine you might have to install multiple versions of MongoDB or you might want to run multiple MongoDB server instances. Both can be done easily using mongoctl.

To install mongoctl on Ubuntu, just run:

sudo pip install mongoctl

In case you don't have installed pip, just run this before the above command:

git clone https://github.com/pypa/pip.git
cd pip
python setup.py install #might need sudo / root

To install the latest stable MongoDB release just run:

mongoctl install-mongodb

Beside installing MongoDB this also creates the config file for your first MongoDB server name "MyServer". You can simply start it using

mongoctl start MyServer

Stopping is as easy as starting it:

mongoctl stop MyServer

By default, journaling is enabled for MongoDB and may eat your hard disk if you're running many MongoDB servers. Having installed MongoDB using mongoctl, the journal of "MyServer" can be found here:

~/mongodb-data/my-server/journal

Listing the directory content shows us, that our instance uses 3GB of hard disk space.

drwxrwxr-x  2 alexzeitler alexzeitler 4,0K Jan 25 00:09 .
drwxrwxr-x 10 alexzeitler alexzeitler 4,0K Jan 24 23:15 ..
-rw-------  1 alexzeitler alexzeitler 1,0G Jan 25 00:09 prealloc.0
-rw-------  1 alexzeitler alexzeitler 1,0G Nov 25 13:04 prealloc.1
-rw-------  1 alexzeitler alexzeitler 1,0G Nov 25 13:04 prealloc.2

While (until the 2.0 release) disabling the journal is a bad idea for production, it is ok for a development environment.

To disable the journaling for "MyServer", head over to ~/.mongoctl and edit the servers.config file.

No find the "MyServer" configuration, which should be the first entry and look like this:

{
    "_id": "MyServer",

    "description" : "My server (single mongod)",

    "cmdOptions": {
        "port": 27017,
        "dbpath": "~/mongodb-data/my-server",
        "directoryperdb": true
    }
}

In order to disable MongoDB journaling, add the nojournal property to cmdOptions:

{
    "_id": "MyServer",

    "description" : "My server (single mongod)",

    "cmdOptions": {
        "port": 27017,
        "dbpath": "~/mongodb-data/my-server",
        "directoryperdb": true,
        "nojournal" : true
    }
}

No, stop your "MyServer" instance and delete the files from the ~/mongodb-data/my-server/journal (you're doing this at your own risk, of course - and as said not in a production environment!) directory.

After starting "MyServer" again, the journal folder should stay empty. That's it!

You can also limit the journal file size to 128MB by setting the smallfiles property to true.

mongoose: Referencing schema in properties or arrays

2015-02-01T01:00:00Z

When using a NoSQL database like MongoDb, most of the time you'll have documents that contain all properties by itself. But there are also scenarios where you might encounter the need for a more relational approach and need to reference other documents by the ObjectIds.

This post will show you how to deal with these references using Node.js and the mongoose ODM.

Lets consider we'll have a users collection and a posts collection, thus we'll have a UserSchema as well as a PostSchema. Posts can be written by users and the can by commented by users.

In this example, well reference the users in posts and comments by their ObjectId reference.

The UserSchema is implemented straight forward and looks like this:

var mongoose = require('mongoose');

var UserSchema = new mongoose.Schema({
    name: String
});

module.exports = mongoose.model("User", UserSchema);

Beside the title property, the PostSchema also defines the reference by ObjectId for the postedBy property of the PostSchema as well as the postedBy property of the comments inside the comments array property:

var mongoose = require('mongoose');

var PostSchema = new mongoose.Schema({
    title: String,
    postedBy: {
        type: mongoose.Schema.Types.ObjectId,
        ref: 'User'
    },
    comments: [{
        text: String,
        postedBy: {
            type: mongoose.Schema.Types.ObjectId,
            ref: 'User'
        }
    }]
});

module.exports = mongoose.model("Post", PostSchema);

Now lets create two users:

require("./database");

var User = require('./User'),
    Post = require('./Post');


var alex = new User({
    name: "Alex"
});

var joe = new User({
    name: "Joe"
})

alex.save();
joe.save();

The interesting part of course is the creation and even more the query for posts. The post is created with the ObjectId references to the users.

var post = new Post({
    title: "Hello World",
    postedBy: alex._id,
    comments: [{
        text: "Nice post!",
        postedBy: joe._id
    }, {
        text: "Thanks :)",
        postedBy: alex._id
    }]
})

Now lets save the Post and after it got created, query for all existing Posts.

post.save(function(error) {
    if (!error) {
        Post.find({})
            .populate('postedBy')
            .populate('comments.postedBy')
            .exec(function(error, posts) {
                console.log(JSON.stringify(posts, null, "\t"))
            })
    }
});

As you can see, the we're using the populate function of mongoose to join the documents when querying for Posts. The first call to populate joins the Users for the postedBy property of the posts whereas the second one joins the Users for the comments.

The Post document in the database looks like this:

{
    "_id" : ObjectId("54cd6669d3e0fb1b302e54e6"),
    "title" : "Hello World",
    "postedBy" : ObjectId("54cd6669d3e0fb1b302e54e4"),
    "comments" : [
        {
            "text" : "Nice post!",
            "postedBy" : ObjectId("54cd6669d3e0fb1b302e54e5"),
            "_id" : ObjectId("54cd6669d3e0fb1b302e54e8")
        },
        {
            "text" : "Thanks :)",
            "postedBy" : ObjectId("54cd6669d3e0fb1b302e54e4"),
            "_id" : ObjectId("54cd6669d3e0fb1b302e54e7")
        }
    ],
    "__v" : 0
}

In contrast, the query result is a full document containing all User references for the Posts.

[
	{
		"_id": "54cd6669d3e0fb1b302e54e6",
		"title": "Hello World",
		"postedBy": {
			"_id": "54cd6669d3e0fb1b302e54e4",
			"name": "Alex",
			"__v": 0
		},
		"__v": 0,
		"comments": [
			{
				"text": "Nice post!",
				"postedBy": {
					"_id": "54cd6669d3e0fb1b302e54e5",
					"name": "Joe",
					"__v": 0
				},
				"_id": "54cd6669d3e0fb1b302e54e8"
			},
			{
				"text": "Thanks :)",
				"postedBy": {
					"_id": "54cd6669d3e0fb1b302e54e4",
					"name": "Alex",
					"__v": 0
				},
				"_id": "54cd6669d3e0fb1b302e54e7"
			}
		]
	}
]

You can find the source code for this sample in this GitHub repository.

#NodeJS / #ExpressJS: Adding routes dynamically at runtime

2015-02-02T01:00:00Z

When running a ExpressJS based API or Website, you may want to add new routes without restarting your ExpressJS host.

Actually, adding routes to ExpressJS at runtime is pretty simple.

First, lets create some "design time" routes for an API endpoint as well as some static content to be served by our ExpressJS application:

var express = require('express');
var app = express();

// development time route
app.get('/api/hello', function(request,response) {
    return response.status(200).send({"hello":"world"})
});

// static file handling
app.use(express.static(__dirname + '/client/app'));


app.listen(3000);

A call to http://localhost:3000/api/hello will return this:

{"hello":"world"}

And the call to http://localhost:3000 will render us some HTML:

<!DOCTYPE html>
<html>
<head lang="en">
    <meta charset="UTF-8">
    <title>Hello World!</title>
</head>
<body>
<h1>Hello World</h1>
</body>
</html>

Nothing special here, move along :)

Now, lets assume we're dropping a new ExpressJS controller into our ./controllers folder at runtime:

module.exports= {
    init : init
};

function init(app){
    app.get('/api/myruntimeroute', function(req,res) {
        res.send({"runtime" : "route"});
    })
}

When calling it's route http://localhost:3000/api/myruntimeroute we'll get a 404. Sad panda.

Now lets drop this piece of code into our app.js before the app.listen(3000) line (this needs to be added before the host is started, of course):

// hook to initialize the dynamic route at runtime
app.post('/api/dynamic', function(req,res) {
    var dynamicController = require('./controllers/RuntimeController');
    dynamicController.init(app);
    res.status(200).send();
});

When sending a POST (curl -X POST http://localhost:3000/api/dynamic) to that endpoint, our controller dropped in at runtime, now gets initalizied and can register it's routes.

Calling http://localhost:3000/api/myruntimeroute now GETs us some fancy JSON:

{"runtime" : "route"}

Looking back to the hookup code, you can see that the name of the controller is already known which of course is just for the sake of simplicity of this sample.

In a real world implementation you might have some other hook up like a user action in your administration which looks for new controllers in a specific folder. Or you might monitor a specfic folder for new controller files. You get the point.

Another approach for dynamic runtime routing could be to have catch some/all route definition which hooks in when all other routes fail.

A small example:

app.get('/api/:dynamicroute', function(req,res) {
    res.send({"param" : req.params.dynamicroute});
});

In this snippet, the part behind the /api/ path is dynamic which means you can have some logic which distributes the requests based on decisions made at runtime.

You can find the source code for this sample in this GitHub repository.

Stop complaining or improve yourself

2015-02-14T14:00:00Z

Working in the IT sector never has offered more choices than nowadays. You can pick from a wide range of hardware platforms supporting an even broader range of operating systems. On top of it, you can pick from a myriad of development platforms and languages.

On the other hand, more and more people working in the IT sector (I'll focus on software development mostly in this rant) start complaining about so much things in their daily use with their hardware, OS or their development environment / programming language (yes, I also come through this hollow alley). If you start complaining publicly on twitter or Facebook et al. you can even get retweets and likes if you show some creativity when doing it.

Let's face the sad truth: it won't change anything until you start acting.

If you don't like^(*) JavaScript, stop complaining and try ES6. If you still don't like^(*) it: ditch it and try something different. Maybe you should focus on HTML5 and CSS3 only. If you don't like^(*) that either, stop doing web development as a whole. You're not forced to do web development at all.

If you don't like^(*) WPF (like me), don't do it, maybe AngularJS might be your frontend framework of choice. But if you're doing the switch, please don't start complaining about it again. If you don't like^(*) it's behavior, try ReactJS or start contributing to AngularJS to improve it.

If you think running JavaScript on the server is plain wrong, simply don't use Node.js/io.js.

If giving up referential integrity is blasphemy for you, don't use (most of the) NoSQL databases.

If you don't like^(*) Windows (any longer - like me), try Linux, OS X or build your own operating system. You may find it hard to change things, but it's up to you to understand and learn things like bash scripting, VIM and all that stuff. If you start experiencing doing better is hard, you might understand why existing things are as they are.

It's your choice to improve yourself or stick with your habbits. But if you stick with them, please do me a favour and stop complaining about them - they have been your own choice.

* Update June 17th 2016:

As Daniel pointed in his Tweet, the usage of the term "Don't like..." might be misleading for some people who don't know me:

@alexzeitler_ I think you wrote a good article in general. Though I disagree with the abuse of "I don't like" // @StefanLieser
— Daniel Marbach (@danielmarbach) June 15, 2016

So here's a little explanation what "Don't like" means: If I wrote "Don't like" in the text above, somebody might get the impression (as Daniel pointed out) "I'm basing all my decisions on taste".

But when I wrote "Don't like" it means: "I tried to solve something with stack x but it didn't work for me in a elegant manner so I tried some other thing which did work much better for that particular problem".

So nothing is based on taste or disgust against a particular stack or company. It's all based on evaluation without prejudices.

Thanks Daniel, for reading and pointing me at this issue.

And as a baseline for this post I would like to add the following:

Everything we're complaining about everyday - especially on social media - is the work of other people.

And even it doesn't look perfect or work in the expected way for us: Others might have worked hard to get it to this point and we should pay respect for their effort - how often did we build something that wasn't perfect at all? 😉

Running ASP.NET 5 Beta 4 in Docker with DNX runtime #aspnet5 #docker

2015-04-27T11:00:00Z

Update [2015-05-02]

As Microsoft has updated it's Dockerfile to support DNX (beta 4 as of this Update), the introduction of this post has become obsolete and you can jump directly over here (in this post).

</end of update> [2015-05-02]

Microsoft recently changed the naming for the ASP.NET 5 runtime from "K" to "DNX". With that, the following K utilities have been renamed:

kpm -> dnu
kvm -> dnvm
k -> dnx

When you're trying to run DNX with the current ASP.NET 5 Docker image being provided by Microsoft, you'll fail.

Based on the Dockerfile Microsoft provides here, I created a local Docker image to be able to run ASP.NET 5 Beta 4 with the new DNX runtime.

The Dockerfile for the base ASP.NET 5 image goes here:

Update [2015-05-01]

You don't have to do the following step, there's also a working Microsoft Dockerfile, just jump to here (in this post), to read the instructions how to use it.

FROM mono:3.12

# Get build dependencies, download/build/install mono 4.1.0
RUN apt-get update -qq \
    && apt-get install -qqy git autoconf libtool automake build-essential mono-devel gettext unzip \
    && git clone https://github.com/mono/mono.git \
    && cd mono \
    && git reset --hard 53dc56ee39a8e3b013231957aca4671b202c6410 \
    && ./autogen.sh --prefix="/usr/local" \
    && make \
    && make install \
    && cd .. \
    && rm mono -r

# Install aspnet 1.0.0-beta4
ENV DNX_FEED https://www.myget.org/F/aspnetmaster/api/v2
ENV DNX_USER_HOME /opt/dnx

RUN curl -sSL https://raw.githubusercontent.com/aspnet/Home/7d6f78ed7a59594ce7cdb54a026f09cb0cbecb2a/dnvminstall.sh | DNX_BRANCH=master sh
RUN bash -c "source $DNX_USER_HOME/dnvm/dnvm.sh \
    && dnvm install 1.0.0-beta4 -a default \
    && dnvm alias default | xargs -i ln -s $DNX_USER_HOME/runtimes/{} $DNX_USER_HOME/runtimes/default"

# Install libuv for Kestrel from source code (binary is not in wheezy and one in jessie is still too old)
RUN LIBUV_VERSION=1.4.2 \
    && curl -sSL https://github.com/libuv/libuv/archive/v${LIBUV_VERSION}.tar.gz | tar zxfv - -C /usr/local/src \
    && cd /usr/local/src/libuv-$LIBUV_VERSION \
    && sh autogen.sh && ./configure && make && make install \
    && rm -rf /usr/local/src/libuv-$LIBUV_VERSION \
    && ldconfig

# Update NuGet feeds

RUN mkdir -p ~/.config/NuGet/
RUN curl -o ~/.config/NuGet/NuGet.Config -sSL https://gist.githubusercontent.com/AlexZeitler/a3412a4d4eeee60f8ce8/raw/45b0b5312845099cdf5da560829e75949d44d65f/NuGet.config

ENV PATH $PATH:$DNX_USER_HOME/runtimes/default/bin

Now lets build the base image:

sudo docker build -t pdmlab/aspnet:1.0.0 .

Based on that, lets create a Dockerfile for our ASP.NET 5 Beta 4 DNX web application:

FROM pdmlab/aspnet:1.0.0
ADD . /app
WORKDIR /app
RUN ["dnu", "restore"]

EXPOSE 5004
ENTRYPOINT ["dnx", "./src/HelloMvc6", "kestrel"]

Update [2015-05-01]

You can also use this Dockerfile using the Microsoft Beta 4 base Image:

FROM microsoft/aspnet:vs-1.0.0-beta4
ADD . /app
WORKDIR /app
RUN ["dnu", "restore"]

EXPOSE 5004
ENTRYPOINT ["dnx", "./src/HelloMvc6", "kestrel"]

</end of update> [2015-05-01]

Update [2015-05-02]

You can use this Dockerfile using the Microsoft DNX Beta 4 base Image:

FROM microsoft/aspnet:1.0.0-beta4
ADD . /app
WORKDIR /app
RUN ["dnu", "restore"]

EXPOSE 5004
ENTRYPOINT ["dnx", "./src/HelloMvc6", "kestrel"]

</end of update> [2015-05-02]

After that, we need to build or application image:

sudo docker build -t aspnet5beta4dnx

With that done, we can run our container:

sudo docker run -t -d -p 80:5004 aspnet5beta4dnx

If erverything went well, you should be able to browse http://localhost/api/values on your host.

The source for the HelloMvc6 application comes here:

project.json:

{
  "webroot": "wwwroot",
  "version": "1.0.0-*",

  "dependencies": {
    "Kestrel": "1.0.0-beta4",
    "Microsoft.AspNet.Mvc": "6.0.0-beta4",
    "Microsoft.AspNet.Server.IIS": "1.0.0-beta4",
    "Microsoft.AspNet.Server.WebListener": "1.0.0-beta4",
    "Microsoft.AspNet.StaticFiles": "1.0.0-beta4"
  },

  "commands": {
    "web": "Microsoft.AspNet.Hosting --server Microsoft.AspNet.Server.WebListener --server.urls http://localhost:5000",
    "kestrel": "Microsoft.AspNet.Hosting --server Kestrel --server.urls http://localhost:5004"
  },

  "frameworks": {
    "dnx451": { },
    "dnxcore50": { }
  },

  "exclude": [
    "wwwroot",
    "node_modules",
    "bower_components"
  ],
  "publishExclude": [
    "node_modules",
    "bower_components",
    "**.xproj",
    "**.user",
    "**.vspscc"
  ]
}

Startup.cs:


using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNet.Builder;
using Microsoft.AspNet.Hosting;
using Microsoft.AspNet.Http;
using Microsoft.AspNet.Routing;
using Microsoft.Framework.DependencyInjection;

namespace HelloMvc6
{
    public class Startup
    {
        public Startup(IHostingEnvironment env)
        {
        }

        // This method gets called by a runtime.
        // Use this method to add services to the container
        public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc();
            // Uncomment the following line to add Web API services which makes it easier to port Web API 2 controllers.
            // You will also need to add the Microsoft.AspNet.Mvc.WebApiCompatShim package to the 'dependencies' section of project.json.
            // services.AddWebApiConventions();
        }

        // Configure is called after ConfigureServices is called.
        public void Configure(IApplicationBuilder app, IHostingEnvironment env)
        {
            // Configure the HTTP request pipeline.
            app.UseStaticFiles();

            // Add MVC to the request pipeline.
            app.UseMvc();
            // Add the following route for porting Web API 2 controllers.
            // routes.MapWebApiRoute("DefaultApi", "api/{controller}/{id?}");
        }
    }
}

ValuesController.cs:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNet.Mvc;

namespace HelloMvc6.Controllers
{
    [Route("api/[controller]")]
    public class ValuesController : Controller
    {
        // GET: api/values
        [HttpGet]
        public IEnumerable<string> Get()
        {
            return new string[] { "value1", "value2" };
        }

        // GET api/values/5
        [HttpGet("{id}")]
        public string Get(int id)
        {
            return "value";
        }

        // POST api/values
        [HttpPost]
        public void Post([FromBody]string value)
        {
        }

        // PUT api/values/5
        [HttpPut("{id}")]
        public void Put(int id, [FromBody]string value)
        {
        }

        // DELETE api/values/5
        [HttpDelete("{id}")]
        public void Delete(int id)
        {
        }
    }
}

lowerCamelCase JSON with ASP.NET MVC 6

2015-05-01T17:00:00Z

With ASP.NET MVC 6 the default output for JSON is still UpperCamelCase.

To change that to lowerCamelCase JSON, simply add this to the ConfigureServices method:

Startup.cs:

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc();
   
    services.ConfigureMvc(options =>
    {
        (options.OutputFormatters.First(f => f.Instance is JsonOutputFormatter).Instance as
            JsonOutputFormatter).SerializerSettings.ContractResolver = 
            new CamelCasePropertyNamesContractResolver();
    });
}

That's it!

Deploying a ASP.NET MVC 6 API as Azure API App in Azure App Services

2015-05-02T10:00:00Z

Setting some context...

Disclaimer: this post is based on Visual Studio 2015 RC, DNX beta 4 and Azure SDK 2.6 and might become obsolete (hopefully pretty fast).

At Build 2015 "The Lesser Scotts" have been showing how to create a Azure API App based on ASP.NET Web API 2 using the Azure SDK Tools in Visual Studio 2013 which you should definitely watch before reading this post.

Well, deploying stable stuff is pretty neat.
But my first thought of course has been "What about ASP.NET MVC 6 on DNX beta 4?".

So I asked the lesser Scotts at Twitter:

Scotts answer was pretty promising:

My next step of course was installing Azure SDK 2.6 for Visual Studio 2015 RC and trying to create a new Azure API App as shown in the video above.

But there were no templates... so back to Twitter - this time Brady Gaster was my victim:

No promising answer but at least some facts :)

Ok, lets do some reverse engineering using Visual Studio 2013 and Azure SDK 2.6 and find out what happens when you're using the SDK tooling - I'll skip this step here and show you, how to get stuff done in Visual Studio 2015 RC and ASP.NET MVC 6 on DNX beta 4 now.

First things first, the ASP.NET MVC 6 API

First, create a new ASP.NET Web Application in Visual Studio 2015 RC:

After this, your solution should look like this:

As the default ValuesController.cs in the Controllers folder is pretty useless (and it will cause problems as you can read later on), we'll delete it and create a SpeakersController.cs instead.

SpeakersController.cs:

using System.Collections.Generic;
using HelloApiApps.Models;
using Microsoft.AspNet.Mvc;

namespace HelloApiApps.Controllers
{
    [Route("api/[controller]")]
    public class SpeakersController
    {
        [HttpGet]
        public IEnumerable<Speaker> GetAll()
        {
            return new List<Speaker>
            {
                new Speaker
                {
                    Id = 1,
                    FirstName = "Scott",
                    LastName = "Hanselman",
                    Twitter = "shanselman"
                },
                new Speaker
                {
                    Id = 2,
                    FirstName = "Scott",
                    LastName = "Hunter",
                    Twitter = "coolcsh"
                },
                new Speaker
                {
                    Id = 3,
                    FirstName = "Damian",
                    LastName = "Edwards",
                    Twitter = "DamianEdwards"
                }
            };
        }
    }
}

We also create a folder Models and create a Speaker.cs in it:

Speaker.cs:

namespace HelloApiApps.Models
{
    public class Speaker
    {
        public int Id { get; set; }
        public string FirstName { get; set; }
        public string LastName { get; set; }
        public string Twitter { get; set; }
    }
}

At this time, you should be able to test your API locally at http://localhost:someport/api/speakers and you should get the JSON representation of our speaker list.

Creating the Swagger API definition file

According to the Scott's video we now would create the Swagger file, but Swashbuckle shown in the video doesn't work with ASP.NET MVC 6 right now.

To the rescue, there's already a work in progress project on GitHub which is porting Swashbuckle to ASP.NET MVC 6: Ahoy!

We create a local clone of Ahoy and for the sake of keeping this post simple, we add the Swashbuckle.Swagger project inside our API Solution as existing project:

Next, we have to register Swashbuckle / Swagger inside our Startup.cs

Startup.cs:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNet.Builder;
using Microsoft.AspNet.Hosting;
using Microsoft.AspNet.Http;
using Microsoft.AspNet.Routing;
using Microsoft.Framework.DependencyInjection;
using Swashbuckle.Application;
using Swashbuckle.Swagger;

namespace HelloApiApps
{
   public class Startup
   {
       public Startup(IHostingEnvironment env)
       {
       }

       // This method gets called by a runtime.
       // Use this method to add services to the container
       public void ConfigureServices(IServiceCollection services)
       {
           services.AddMvc();
           // Uncomment the following line to add Web API services which makes it easier to port Web API 2 controllers.
           // You will also need to add the Microsoft.AspNet.Mvc.WebApiCompatShim package to the 'dependencies' section of project.json.
           // services.AddWebApiConventions();

           services.AddSwagger(s =>
           {
               s.SwaggerGenerator(c =>
               {
                   c.Schemes = new[] { "http", "https" };
                   c.SingleApiVersion(new Info
                   {
                       Version = "v1",
                       Title = "Swashbuckle Sample API",
                       Description = "A sample API for testing Swashbuckle",
                       TermsOfService = "Some terms ..."
                   });
               });

               s.SchemaGenerator(opt => opt.DescribeAllEnumsAsStrings = true);
           });
       }

       // Configure is called after ConfigureServices is called.
       public void Configure(IApplicationBuilder app, IHostingEnvironment env)
       {
           // Configure the HTTP request pipeline.
           app.UseStaticFiles();

           // Add MVC to the request pipeline.
           app.UseMvc();
           // Add the following route for porting Web API 2 controllers.
           // routes.MapWebApiRoute("DefaultApi", "api/{controller}/{id?}");

           // Add MVC to the request pipeline.
           app.UseMvc(routes =>
           {
               routes.EnableSwagger("swagger/docs/{apiVersion}");
           });
       }
   }
}

The default Swagger URL for Swashbuckle has been (as shown in the video): http://somehost:someport/swagger/docs/v1.

By default, with Ahoy this has changed to http://somehost:someport/swagger/v1/swagger.json whereas in both cases v1 depends on the Version property being set during Swashbuckle registration in Startup.cs inside the ConfigureServices method in the code shown above.

Thus, we have to change the route definition back to the old format as Azure API Apps expect it in that format. You can see that inside the Configure method of the Startup.cs in the code shown above.

Next, we can open up our App in a browser again and browse to http://localhost:someport/swagger/docs/v1 and we should get the JSON representation.

Adding Azure API Apps Metadata

Now we need to add the Metadata for the Azure API Apps manually as we don't have the tooling support right now...

First, add a JSON file named apiapp.json in the root of the API App project:

Then paste this content into it:

{
 "$schema": "http://json-schema.org/schemas/2014-11-01/apiapp.json#",
 "id": "HelloApiApps",
 "namespace": "microsoft.com",
 "gateway": "2015-01-14",
 "version": "1.0.0",
 "title": "HelloApiApps",
 "summary": "",
 "author": "",
 "endpoints": null
}

Next, add the following folders and files to your wwwroot folder in the API App solution:

The content of the apiDefinition.swagger.json is the output from http://localhost:someport/swagger/docs/v1. Copy and paste it into the file.

Important Note: Make sure your API Controllers don't contain ambiguous method names (e.g. "Get" twice), this will cause problems at the moment. Thanks to @Mohit for sorting that out!

The last file required, is the apiappconfig.azureresource.json and it's content is this:

{
 "$schema": "http://schemas.management.azure.com/schemas/2014-04-01-preview/deploymentTemplate.json#",
 "contentVersion": "1.0.0.0",
 "parameters": {
   "$system": {
     "type": "Object"
   }
 },
 "resources": []
}

<Update [2015/05/02]>: Instead of providing a static snapshot of your Swagger API definition, you can also provide an endpoint where the current swagger definition can be read from. This solves two problems: the route can be the new route template Ahoy introduces and your Swagger definition is always up to date when add new API endpoints (Controllers / Methods).

Just update the apiapp.json and add an fill the endpoint property (please note that I'm use the new default Ahoy route here):

{
"$schema": "http://json-schema.org/schemas/2014-11-01/apiapp.json#",
"id": "HelloApiApps",
"namespace": "microsoft.com",
"gateway": "2015-01-14",
"version": "1.0.0",
"title": "HelloApiApps",
"summary": "",
"author": "",
"endpoints": {
      "apiDefinition": "/swagger/v1/swagger.json"
  }
}

Kudos go to @pkefal for the hint (By the way: if you want to create API Apps using Node.js you should definitely read his article)

</end of update [2015/05/02]>

Another step, the Azure SDK tooling does, is adding two NuGet packages and we have to do that also. Update your project.json and add Microsoft.Azure.AppService.ApiApps.Service and System.IdentityModel.Tokens.Jwtto it.

{
 "webroot": "wwwroot",
 "version": "1.0.0-*",

 "dependencies": {
   "Microsoft.AspNet.Mvc": "6.0.0-beta4",
   "Microsoft.AspNet.Server.IIS": "1.0.0-beta4",
   "Microsoft.AspNet.Server.WebListener": "1.0.0-beta4",
   "Microsoft.Azure.AppService.ApiApps.Service": "0.9.40",
   "System.IdentityModel.Tokens.Jwt": "4.0.2.202250711",
   "Microsoft.AspNet.StaticFiles": "1.0.0-beta4",
   "Swashbuckle.Swagger": "1.0.0-*"
 },

 "commands": {
   "web": "Microsoft.AspNet.Hosting --server Microsoft.AspNet.Server.WebListener --server.urls http://localhost:5000"
 },

 "frameworks": {
   "dnx451": { },
   "dnxcore50": { }
 },

 "exclude": [
   "wwwroot",
   "node_modules",
   "bower_components"
 ],
 "publishExclude": [
   "node_modules",
   "bower_components",
   "**.xproj",
   "**.user",
   "**.vspscc"
 ]
}

Publishing the API App

If there were tooling support, you could create a new Azure API App using the tooling. Yet: no tooling, thus we have to use the new Azure Portal.

Disclaimer: Depending on your plan and the settings, this will cost you money!

After a few seconds, you'll get the success notification inside the Azure Portal and you should have a new tile on the Portal startpage and clicking on it should get you some details:

Now make sure to set the "Access Level" inside the "Settings" / "Application Settings" to "public (anonymous)" and click the "Save" button afterwards:

Back to Visual Studio 2015 RC, we can now publish our Azure API App by right clicking the project and selecting "Publish...":

The next dialog allows you to select where to publish:

Select "Microsoft Azure Web Apps" and click "Next".

Now from "Existing Web Apps", select the API App you just created inside the Azure Portal and click "OK":

The next dialog sums up the connection details and can be confirmed with "Next":

During the next step, you can choose your DNX version to be used for the API App - the defaults are ok, click "Next":

The last step is to hit the "Publish" button:

The publishing process should take only a few seconds:

When it is finished, it should open up your default browser showing you this:

Back to the Azure Portal you should now be able to click on the "API Definition" tile and see the API Operations and be able to download the Swagger using the button above the list of Operations.

That's it!

Integration-testing ASP.NET 5 / MVC 6 Controllers on DNX Beta 4

2015-05-16T21:00:00Z

In ASP.NET 5 bootstrapping a self host test server has changed compared to ASP.NET 4 / Web API.

This post will show you how you can run integration tests using ASP.NET 5 / MVC 6 API Controllers on Beta 4 of DNX.

First, the Controller implementation:

CustomersController.cs:

[Route("api/[controller]")]
public class CustomersController
{
    [HttpGet]
    public IActionResult GetAll()
    {
        return new ObjectResult(
            new List<Customer>()
            {
                new Customer
                {
                    CompanyName = "PDMLab",
                    AddressLine = "Ludwig-Erhard-Allee 10",
                    ZipCode = "76131",
                    City = "Karlsruhe",
                    Website = "https://pdmlab.com"
                }
            });
    }
}

Our tests will use Xunit, so we'll add Xunit to our project.json file:

...
 "dependencies": {
    "Microsoft.AspNet.Mvc": "6.0.0-beta4",
    "Microsoft.AspNet.Server.IIS": "1.0.0-beta4",
    "Microsoft.AspNet.Server.WebListener": "1.0.0-beta4",
    "Microsoft.AspNet.StaticFiles": "1.0.0-beta4",
    "xunit": "2.1.0-*",
    "xunit.runner.dnx": "2.1.0-beta2-build79",
    "xunit.runner.visualstudio": "2.1.0-beta1-build1051"
  },
...

Furthermore, our HttpClient we're using resides in Microsoft.AspNet.WebApi.Client which we'll add also to our project.json file:

...
 "dependencies": {
    "Microsoft.AspNet.Mvc": "6.0.0-beta4",
    "Microsoft.AspNet.Server.IIS": "1.0.0-beta4",
    "Microsoft.AspNet.Server.WebListener": "1.0.0-beta4",
    "Microsoft.AspNet.StaticFiles": "1.0.0-beta4",
    "Microsoft.AspNet.WebApi.Client": "5.2.3",
    "xunit": "2.1.0-*",
    "xunit.runner.dnx": "2.1.0-beta2-build79",
    "xunit.runner.visualstudio": "2.1.0-beta1-build1051"
  },
...

Finally, we need Kestrel to run our tests on *nix based systems as well as Microsoft.AspNet.Hosting which contains the classes required for bootstrapping a self host server - :

...
  "dependencies": {
    "Kestrel": "1.0.0-beta4",
    "Microsoft.AspNet.Hosting": "1.0.0-beta4",
    "Microsoft.AspNet.Mvc": "6.0.0-beta4",
    "Microsoft.AspNet.Server.IIS": "1.0.0-beta4",
    "Microsoft.AspNet.Server.WebListener": "1.0.0-beta4",
    "Microsoft.AspNet.StaticFiles": "1.0.0-beta4",
    "Microsoft.AspNet.WebApi.Client": "5.2.3",
    "xunit": "2.1.0-*",
    "xunit.runner.dnx": "2.1.0-beta2-build79",
    "xunit.runner.visualstudio": "2.1.0-beta1-build1051"
  },
...

The final part required is the test itself:

public class CustomerControllerIntegrationTest
    {
        [Fact]
        public void ShouldReturnCustomer()
        {
            var config = new Configuration();
            config.AddCommandLine(new[] { "--server.urls", "http://localhost:5001" });
            
            var serverFactoryLocation = string.Empty;
            if(!IsMono()) {
                serverFactoryLocation = "Microsoft.AspNet.Server.WebListener";
            } else {
                serverFactoryLocation = "Kestrel";
            }
            var context = new HostingContext()
            {
                Configuration = config,
                ServerFactoryLocation = serverFactoryLocation,
                ApplicationName = "AspNet5IntegrationTesting",
                StartupMethods = new StartupMethods(builder => builder.UseMvc(), services =>
                {
                    services.AddMvc();
                    return services.BuildServiceProvider();
                })
            };


            using (new HostingEngine().Start(context))
            {
                var client = new HttpClient();
                var customers = client.GetAsync("http://localhost:5001/api/customers").Result
                    .Content.ReadAsAsync<List<Customer>>().Result;

                Assert.Equal(customers[0].CompanyName,"PDMLab");
            }
        }
        
        public static bool IsMono()
        {
            return Type.GetType("Mono.Runtime") != null;
        }
 
    }

The implementation is pretty straight forward:

First we're adding the host and port our test server should listen on to our application configuration.

Then we're checking if we're running on mono and depdending on the result, we're bootstrapping Kestrel oder WebListener.

After that we're bootstrapping a HostingContext instance which configures our StartupMethods (which contains the stuff that resides in your Startup.cs normally), Configuration and the host to use.

Using this context we're firing up a new HostingEngine instance which gets disposedd after the assertions have finished.

That's it... almost, because there's one caveat:

The tests currently fail on Kestrel / *nix with this error:

xUnit.net DNX test runner (64-bit DNX 4.5.1)
Copyright (C) 2015 Outercurve Foundation.

Discovering: AspNet5IntegrationTesting
Discovered:  AspNet5IntegrationTesting
Starting:    AspNet5IntegrationTesting
   AspNet5IntegrationTesting.Tests.CustomerControllerIntegrationTest.ShouldReturnCustomer [FAIL]
      System.ArgumentException : GCHandle value belongs to a different domain
      Stack Trace:
           at System.Runtime.InteropServices.GCHandle.op_Explicit (IntPtr value) [0x00000] in <filename unknown>:0 
           at System.Runtime.InteropServices.GCHandle.FromIntPtr (IntPtr value) [0x00000] in <filename unknown>:0 
           at Microsoft.AspNet.Server.Kestrel.Networking.UvMemory.DestroyMemory (IntPtr memory) [0x00000] in <filename unknown>:0 
           at Microsoft.AspNet.Server.Kestrel.Networking.UvLoopHandle.ReleaseHandle () [0x00000] in <filename unknown>:0 
           at System.Runtime.InteropServices.SafeHandle.RunRelease () [0x00000] in <filename unknown>:0 
           at System.Runtime.InteropServices.SafeHandle.Dispose (Boolean disposing) [0x00000] in <filename unknown>:0 
           at System.Runtime.InteropServices.SafeHandle.Dispose () [0x00000] in <filename unknown>:0 
           at Microsoft.AspNet.Server.Kestrel.KestrelThread.ThreadStart (System.Object parameter) [0x00000] in <filename unknown>:0 
         --- End of stack trace from previous location where exception was thrown ---
           at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw () [0x00000] in <filename unknown>:0 
           at Microsoft.AspNet.Server.Kestrel.KestrelThread.Stop (TimeSpan timeout) [0x00000] in <filename unknown>:0 
           at Microsoft.AspNet.Server.Kestrel.KestrelEngine.Dispose () [0x00000] in <filename unknown>:0 
           at Kestrel.ServerFactory+<>c__DisplayClass3_0.<Start>b__1 () [0x00000] in <filename unknown>:0 
           at Microsoft.AspNet.Server.Kestrel.Disposable.Dispose (Boolean disposing) [0x00000] in <filename unknown>:0 
           at Microsoft.AspNet.Server.Kestrel.Disposable.Dispose () [0x00000] in <filename unknown>:0 
           at Microsoft.AspNet.Hosting.HostingEngine+<>c__DisplayClass9_0.<Start>b__1 () [0x00000] in <filename unknown>:0 
           at Microsoft.AspNet.Hosting.HostingEngine+Disposable.Dispose () [0x00000] in <filename unknown>:0 
           at AspNet5IntegrationTesting.Tests.CustomerControllerIntegrationTest.ShouldReturnCustomer () [0x00000] in <filename unknown>:0 
           at (wrapper managed-to-native) System.Reflection.MonoMethod:InternalInvoke (System.Reflection.MonoMethod,object,object[],System.Exception&)
           at System.Reflection.MonoMethod.Invoke (System.Object obj, BindingFlags invokeAttr, System.Reflection.Binder binder, System.Object[] parameters, System.Globalization.CultureInfo culture) [0x00000] in <filename unknown>:0 
Finished:    AspNet5IntegrationTesting

=== TEST EXECUTION SUMMARY ===
   AspNet5IntegrationTesting  Total: 1, Errors: 0, Failed: 1, Skipped: 0, Time: 0.697s

If somebody has an idea about this, please send me a pull request at GitHub (yes, you can grab the source over there) ;-)

Update [2015/05/17]: This is a known Kestrel issue as described here (Description starts here) and a fix is on the way.

A lap around AWS and docker-machine

2015-08-16T21:00:00Z

This post will show you how can create a Docker Machine instance on AWS (EC2) starting from scratch. This means you're starting with your free AWS account with nothing configured after you have signed up for your free AWS trial account.

To create a Docker machine instance in AWS, the docker-machine command requires several params for the AWS driver.

At a minimum, we need to provide these params:

amazonec2-access-key
amazonec2-secret-key
amazonec2-region
amazonec2-zone
amazonec2-vpc-id

To get the amazonec2-access-key and the amazonec2-secret-key we need to have an Amazon EC2 Access Key and an Amazon EC2 Secret Key.

Both of them can be obtained by creating a user in IAM.

Clicking on the "Create New Users" button will bring up this view where we create a new user named "awsdockeruser":

Make sure to check "Generate an access key for each user".

After creating the user, we'll get both keys:

Make sure to create a copy at safe place as this is the last time you'll see them in IAM.

In order to manage AWS EC2 instances we need the appropriate permissions. To assign the permission to manage EC2 instances our awsdockeruser needs to be a member of a group which has that permission.

So lets create that group in the IAM dashboard:

We'll called it "awsdockergroup"

Next, assign the policy to manage EC2 instances (there might be lower privileges that are sufficient):

Next, lets add the "awsdockeruser" to our group:

Next, we need to know region, zone and VPC id. These can be obtained by using the AWS CLI.

On Linux and OS X, it can be installed using PIP package manager.

pip install awscli

Then AWS CLI needs to be configured:

aws configure

AWS CLI configurations asks you for your AWS Access Key ID, your AWS Secret Access Key (remember them? 😀), Default region name (codes can be found here - I've choosen eu-central-1), and Default output format which I set to json.

To get the vpc-id, just run:

aws ec2 describe-subnets

The output will look like this:

{
    "Subnets": [
        {
            "VpcId": "<avpcid>",
            "CidrBlock": "172.31.0.0/20",
            "MapPublicIpOnLaunch": true,
            "DefaultForAz": true,
            "State": "available",
            "AvailabilityZone": "eu-central-1a",
            "SubnetId": "<asubnetid>",
            "AvailableIpAddressCount": 4091
        },
        {
            "VpcId": "<anothervpcid>",
            "CidrBlock": "172.31.16.0/20",
            "MapPublicIpOnLaunch": true,
            "DefaultForAz": true,
            "State": "available",
            "AvailabilityZone": "eu-central-1b",
            "SubnetId": "<anothersubnetid>",
            "AvailableIpAddressCount": 4091
        }
    ]
}

The amazonec2-zone param is the last character of the AvailabilityZone of the subnet you choose to use, so a or b here.

Ok, it's time to spin up our Docker machine instance...

docker-machine create \ 
				-d amazonec2 \
				--amazonec2-access-key <YOURACCESSKEY> \
				--amazonec2-secret-key <YOURSECRETKEY> \
				--amazonec2-zone a \
				--amazonec2-region eu-central-1 \
				--amazonec2-vpc-id <YOURVPCID> 
				awsdocker

After about 60 seconds, your console should confirm your machine is ready to rock'n roll

Launching instance...
To see how to connect Docker to this machine, run: docker-machine env awsdocker

To connect to the machine, run this command:

eval $(docker-machine env awsdocker)

To make sure everything works as expected, just run docker ps.

If you're working with various machines, you might want to know which is your current active machine:

You can have this in your prompt if you use my bash prompt definiton from here.

Using docker-machine ip awsdocker you can get the public IP address of your machine.

If you're deploying some containers, you might wonder, why you can`t access your containers exposed ports like http://<machine-ip>:<someport>: because firewall 😱.

So head over to the EC2 dashboard "Security Groups" section, select your "docker-machine" Security Group (which has been created when spinning up your machine) and make sure to allow some inbound traffic:

Happy shipping! 😀

Docker Machine: NS_ERROR_FAILURE Failed to create the host-only adapter

2016-01-16T17:00:00Z

If you try to start a docker machine using docker-machine start <machinename>, you might receive this error message:

Progress state: NS_ERROR_FAILURE
VBoxManage: error: Failed to create the host-only adapter
VBoxManage: error: VBoxNetAdpCtl: Error while adding new interface: failed to open /dev/vboxnetctl: No such file or directory
VBoxManage: error: Details: code NS_ERROR_FAILURE (0x80004005), component HostNetworkInterface, interface IHostNetworkInterface
VBoxManage: error: Context: "int handleCreate(HandlerArg*, int, int*)" at line 66 of file VBoxManageHostonly.cpp

To resolve this issue, you have to setup the vboxdrv kernel module using

sudo /etc/init.d/vboxdrv setup

Rename Visual Studio project including files, folders and namespaces

2016-01-29T17:00:00Z

TL;DR

It's 2016 and Visual Studio doesn't support us in renaming Projects including files, folders and namespaces.

Considering you have a Visual Studio solution named PDMLab.AwesomeProject.WithAnUglyTypo and this solution contains multiple projects all starting with PDMLab.AwesomeProject.WithAnUglyTypo. The projects also may contain default namespace names starting using the solution name and the assemblies might be named accordingly.

One solution is to use Notepad++ to replace every occurrence of PDMLab.AwesomeProject.WithAnUglyTypo and rename the folders by hand or another tool.
Well, this works but I'm more a console user...

That said, the solution shown below asumes you have git bash installed.

Replacing the contents like namespaces in the files:

# run this in the root folder of your project
find . -name "*.*" -print0 | xargs -0 sed -i '' -e 's/PDMLab\.AwesomeProject\.WithAnUglyTypo/PDMLab.AwesomeProject.WithoutAnUglyTypo/g'

Renaming files and folders:

# run this in the root folder of your project
for i in $(find * -maxdepth 1); do mv $i $(echo $i | sed 's/PDMLab\.AwesomeProject\.WithAnUglyTypo/PDMLab.AwesomeProject.WithoutAnUglyTypo/'); done

The advantage of this solution: You can create an alias for both commands that expects the old and new name as an param and you're done.

Make sure you have a backup of your files before you try that - I'm not responsible if something goes wrong...

Happy renaming :)

Chrome crashes on Ubuntu in VMware Workstation

2016-01-29T17:30:00Z

If you're using Chrome on Ubuntu in a VMware Workstation VM it is likely, that it has been crashing after being in the background for a while. Sometimes it also kills the VM entirely.

For me the solution was to disable hardware accelartion completely - the performance isn't that bad after all.

Go to Chrome settings, then show advanced settings and disable hardware acceleration:

Workflows: using Docker Machine and Docker Compose together in development

2016-02-01T01:00:00Z

We're using the Docker eco system now for a while in development and production.
As you may know, the Docker eco system not only consists of the Docker engine (client and server), but it also provides Docker Machine and Docker Compose.
While Docker Compose makes linking containers much easier, Docker Machine provides an abstraction for your environment where your Docker engine is being executed in. Thus, Machine allows you to manage your Docker engine Host in a consistent way no matter whether you're on AWS, Azure or on premise - or even your local dev environment.

Docker Machine and Docker Compose work together pretty well in production, but when using them in development, you might experience some issues - some of which I'll describe in this post and show solutions for it.

This post is not about using Docker, Docker Machine or Compose in production!

Plain Docker development workflow with Node.js / Express

First, some basics. Let's consider we're composing an Docker application using a MongoDb database and we're implementing a Node.js application that uses MongoDb.

A basic Docker workflow without Machine and Compose would look like this:

Create a Dockerfile for our Node.js application:

FROM node:4.2.3
EXPOSE 3000
EXPOSE 5858
COPY . /app
WORKDIR /app

RUN cd /app; npm install
CMD ["node", "app.js"]

Create our simplified Node.js appliation in app.js:

var express = require('express');
var app = express();

app.use(express.static('public'));
app.listen(3000);

Place an index.html inside the public folder:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Hello</title>
</head>
<body>
Hello
</body>
</html>

Now we can build our image like this:

docker build -t my-node-app .

Then we can run our container based on this image:

docker run -it --name=my-node-app-container -p 3000:3000 my-node-app

Pointing our browser to http://localhost:3000/ will return this result:

If we're changing something in our index.html, we have to stop and remove our container, rebuild the image and start the container again:

docker stop my-node-app-container
docker rm my-node-app-container
docker build -t my-node-app .
docker run -it --name=my-node-app-container -p 3000:3000 my-node-app

Also this happens quite fast, we can get it even faster by mounting our local project folder as a volume for our container:

docker build -t my-node-app .
docker run -d -it --name=my-node-app-container -v $(pwd):/app -p 3000:3000 my-node-app

By adding the -v $(pwd):/app parameter to our docker run command, we're mapping the local project folder into the /app folder in our container.

Now we can modify the content in below our public folder and just hit F5 in our browser to get the latest changes.

Let's get a bit further and add an API to our application and change the app.js as follows:

var express = require('express');
var app = express();

app.use(express.static('public'));

app.get('/hello', function (req, res) {
    res.send('world');
});

app.listen(3000);

After this, we can run HTTPIe (or curl / wget) http get localhost:3000/hello and receive an output like this:

HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 5
Content-Type: text/html; charset=utf-8
Date: Sat, 23 Jan 2016 20:55:07 GMT
ETag: W/"5-fXkwN6B2AYZXSwKC8vQ15w"
X-Powered-By: Express

world

Changing something in the API and running HTTPIe won't result in updated output.
This is because express needs to be initialized again to run the app with the changes made.

We have two options to re-initialize the container: restart the container or kill it and run it again.

Restarting the container is a single command: docker restart my-node-app-container.
Also this command is pretty simple, it may take a few seconds to gracefully stop and start the container.

The second option is a bit faster and looks like this:

docker kill my-node-app-container
docker run -d -it --name=my-node-app-container -v $(pwd):/app -p 3000:3000 my-node-app

Plain Docker workflow with Node.js and MongoDb

As said earlier in this post, our goal is to have an application that runs on Node.js and uses MongoDb.
Adding MongoDb to our game is as simple as this:

docker run -d -it --name=some-mongo -p 27017:27017 mongo

In order to connect our Node.js App container with the MongoDb container, we have to run it using:

docker run -d -it --name=my-node-app-container -v $(pwd):/app -p 3000:3000 --link some-mongo:mongo my-node-app

Now let's change our Node.js application to use MongoDb and write the request body of a POST to /hello to the documents colleciton in MongoDb:

var express = require('express');
var app = express();
var bodyparser = require('body-parser');
var MongoClient = require('mongodb').MongoClient;
var url = 'mongodb://' + process.env.MONGO_PORT_27017_TCP_ADDR + ':27017/dockerdemo';
var db;

MongoClient.connect(url, function (err, database) {
    console.log("Connected correctly to server");
    db = database;
});

app.use(bodyparser.json());
app.use(express.static('public'));

var insertDocument = function (db, document, callback) {
    // Get the documents collection
    var collection = db.collection('documents');
    // Insert some documents
    collection.insertOne(document, function (err, result) {
        callback(err, JSON.stringify(result.ops[0]));
    });
};

app.post('/hello', function (req, res) {
    var data = req.body;
    insertDocument(db, data, function(err, result) {
        res.status(201).send(result)
    })
});

app.get('/hello', function (req, res) {
    res.send('world');
});

app.listen(3000);

Sending a request using to our API like this http post http://localhost:3000/hello name=PDMLab will result in a successful response:

HTTP/1.1 201 Created
Connection: keep-alive
Content-Length: 50
Content-Type: application/json; charset=utf-8
Date: Wed, 27 Jan 2016 21:54:21 GMT
ETag: W/"32-YLqScoop9RrYa0x7JH+FIg"
X-Powered-By: Express

{
    "_id": "56a93c8d51a0630100b28294", 
    "name": "PDMLab"
}

Using nodemon we can kill and start the containers as shown before and we have a nice development workflow.

Simplifying container linking using Docker Compose

Now lets go one step further and add Docker Compose to handle the container linking.

Using Compose, you don't link containers using the Docker CLI, but instead you create a file named docker-compose.yml (you can name it as you like but the Compose CLI uses this by default).

The Compose file for our application looks like this:

mongo:
  image: mongo:2.6.11
  ports:
   - "27017:27017"
application:
  build: .
  command:  node --debug=5858 app.js --color=always
  ports:
   - "3000:3000"
   - "5858:5858"
  volumes :
  - ./:/app
  links:
   - mongo

When issuing the http POST as shown above, we'll get a similar result.

Refreshing our index.html without restarting the containers still works. This happens because we're mapping the current folder to the /app folder using inside the volumes section of the appliation container definition.

Restarting the container can be automated using nodemon like this:

nodemon -x docker-compose up

This will ensure that changes to the API part of our application are applied as shown before.

Adding Docker Machine to the scene

Now it's time to introduce Docker Machine and show how it plays together with our existing setup.

We can simply create a new Docker Machine instance named default:

docker-machine create --driver=virtualbox default

To make sure our Docker client talks to the Docker engine in our default machine, we'll update the environment:

eval $(docker-machine env default)

First, lets try to build and run our first sample from above with Docker Machine:

docker run -d -it --name=my-node-app-container -p 3000:3000 my-node-app

Pointing the browser again to http://localhost:3000 will fail to access the site.

This happens because port 3000 is not open in VirtualBox where the VM (our machine named default) is running. To solve this, we can open the port using the VirtualBox port forwading Network setting for the machine or simply run VBoxManage on the console:

VBoxManage modifyvm "default" --natpf1 "default,tcp,,3000,,3000"

Trying to open the website again then will result in the expected Hello World response.

Another option (my preference) to access our application running in the machine, is to use the IP address of the machine. To retrieve it, we call

docker-machine ip default

This will result, for example, in 192.168.99.100 and pointing our browser to http://192.168.99.100:3000/ will return the expected response as well.

Docker Machine and Volumes

The next thing we tried was the usage of Volumes and we'll now try this with Docker Machine as well.

Our command was this, so lets use it again:

docker run -d -it --name=my-node-app-container -v $(pwd):/app -p 3000:3000 my-node-app

The console result will look fine at a first sight:

098b5a3387df42092bec984105bf9f6725e11088d3f62d72a893f586cb33bc50

But when we try to open the application in our browser, it fails again.

Looking at our list of running containers using docker ps doesn't show our my-node-app-container running.
What happened?

Let's dig a bit deeper using docker logs my-node-app-container.

The result will look like this:

module.js:339
    throw err;
    ^

Error: Cannot find module '/app/app.js'
    at Function.Module._resolveFilename (module.js:337:15)
    at Function.Module._load (module.js:287:25)
    at Function.Module.runMain (module.js:467:10)
    at startup (node.js:136:18)
    at node.js:963:3

The reason for this is that we're telling the Docker engine to map our local directory to the /app folder inside the container. The problem here: our local folder doesn't exist in the Docker Machine default thats running inside VirtualBox.

Docker Machine provides a solution for this. We can use the ssh command provided by Docker Machine to create the "local" folder inside the machine and then use the Docker Machine scp command to copy the files from our host into that folder inside the machine:

docker-machine ssh default mkdir -p $(pwd)
docker-machine scp -r . default:$(pwd)

Copying the files has to be done every time our source code changes. Because the scp command is a all or nothing operation, I was looking for another solution that copies only the file changed. One option would be Grunt or Gulp to get the particular file change but I'm not a friend of these tools.

A wide spread tool is rsync which exactly does what we want: copy all changed files.

The good part of the story: in the end it works. The bad part: There's "a little" work to do.

First, to make sure all further rsync commands work as expected, we need to get the SSH key to be used by rsync.

This is done by the following commands:

eval $(ssh-agent)
ssh-add ~/.docker/machine/machines/default/id_rsa

Next, we need to know that the OS running inside Docker Machine does NOT provide an rsync installation out of the box. To the resuce, boot2docker (based on Tiny Core Linux), the OS running inside Docker Machine, comes with an package manager named tce and using the following command, we can installed rsync inside our Docker Machine:

docker-machine ssh default -- tce-load -wi rsync

Next, we have to create the directory with the same path as our local path in our Docker Machine and then sync our local directory to the Docker Machine:

docker-machine ssh default mkdir -p $(pwd)
rsync -avzhe ssh --relative --omit-dir-times --progress ./ docker@$(docker-machine ip default):$(pwd)

After this, we'll kill our my-node-app-container and restart it:

docker kill my-node-app-container
docker start my-node-app-container

In the end, you'll put the rsync command and restarting of the container into a .sh file and call this from nodemon.

Running this container together with the MongoDb container works similar to the sample shown in the section without MongoDb but of course with the rsync stuff applied.

Docker Machine and Docker Compose together

The last part of this post will show how to run your containers in Docker Machine and get the composition done by Docker Compose.

Our docker-compose.yml file looks exactly the same as before:

mongo:
  image: mongo:2.6.11
  ports:
   - "27017:27017"
application:
  build: .
  command:  node --debug=5858 app.js --color=always
  ports:
   - "3000:3000"
   - "5858:5858"
  volumes:
  - ./:/app
  links:
   - mongo

In order to get Docker Machine and Compose work together and have a smooth development workflow, you'll have to add the docker-compose up command to your aforementioned .sh script and restart this by nodemon like this:

nodemon -x syncandrestartcontainers.sh

Finally, syncandrestartcontainers.sh will look like this:

eval $(ssh-agent)
ssh-add ~/.docker/machine/machines/default/id_rsa
rsync -avzhe ssh --relative --omit-dir-times --progress ./ docker@$(docker-machine ip default):$(pwd)
docker-compose up

Some tips for the praxis when using this workflow:

Before starting this workflow

stop your Docker Machine and restart it using docker-machine restart default (don't forget eval $(docker-machine env default) after it)
delete the "local" directory inside the Docker Machine using docker-machine ssh default sudo -i "sudo rm -rf $(pwd)"
create the "local" directory inside the Docker Machine using docker-machine ssh default mkdir -p $(pwd)

Update 2016, 3rd February: One more thing... Docker networking

As suggested in the comments, this update of the post shows you how to use Docker networking which has been introduced in Docker 1.9.
You can read the basics about Docker network here - please read them first and then continue here...

Welcome back ;-)

First, lets create a custom bridged network named my-app-network:

docker network create --driver=bridge my-app-network

Next, we'll start our MongoDb container connected to the network:

docker run -d -it --name=some-mongo --net=my-app-network -p 27017:27017 mongo:2.6.11

As Docker networking doesn't use environment variables to share connection settings but the container names instead, we need to change the MongoDb connection string in our app.js accordingly:

var url = 'mongodb://some-mongo:27017/dockerdemo';

Then, rebuild our image:

docker build -t my-node-app .

And finally, run our app container connected to the network as well:

docker run -d -it --name=my-node-app-container -v $(pwd):/app -p 3000:3000 --net=my-app-network  my-node-app

Issuing a http post http://localhost:3000/hello name=PDMLab again works fine as before.

Docker networking also works fine with Docker Machine, just make sure you follow the steps (rsync etc.) shown above.

Docker networking in Docker Compose is experimental at the moment so I won't show that now.

End of Update 2016, 3rd February

Happy developing using Docker Machine and Compose ;-)

P.S.: If you came up with other solutions, please let me know in the comments.

Resizing a VMware Workstation VM partition using GParted - get the swap partition out of my way!

2016-02-04T21:00:00Z

TL;DR Hard Disk space can only be replaced with more Hard Disk space

Disclaimer: If you're doing things wrong described here you'll loose your data - create a backup first!

Nowadays it's casual to use VMs for development environments. It's also casual that projects grow and you run out of disk space inside the VMs. Luckily, on the host there's always enough space available which can be assigned to an existing VM (isn't it?).

Expanding the partition in the VMware Hardware options / hard disk details is pretty easy. Just stop the VM, click the expand button and increase as required:

Now we have some more space for partitions in our VM but we want to increase the size of an existing partition. To manage the partitions, we're using GParted, which is available as bootable ISO-Image.

Assign the downloaded ISO in your VMware CD-ROM drive and boot from it. You can select the boot device if you hit ESC right after powering on the VM.

If the boot sequence is to fast, you can add this line to your VMs .vmx file:

bios.bootDelay = "2000"

This will delay the boot sequence for 2000 ms and show the options.

If you're running Ubuntu in your VM, it is likely that there might be a swap partition (/dev/sda5 here) between the main partition and the aforementioned created, unallocated new space and your partitions might look like this:

What we want to achieve now, is to merge the 10 GB unallocated space at the end of the list to the /dev/sda1 partition.

First, we'll select /dev/sda2 (NOT /dev/sda5!):

Then, we click "Resize/Move":

Next, we increase the size of /dev/sda2 to use all available space:

Now we select /dev/sda5 and click Resize/Move again:

In this step, we move /dev/sda5 inside /dev/sda2 to right end:

Then again, we select /dev/sda2:

After clicking Resize/Move now we shrink /dev/sda2 to the size of /dev/sda5 by moving the left arrow to the right until it is blocked:

Now we select /dev/sda1 again:

After clicking "Resize/Move" again, we finally can expand /dev/sda1 to the right:

The final step is hitting the "Apply" button, confirm everything, cross fingers and wait for the operations to succeed.

As GParted already tells you in almost every step: Be careful with what you're doing and create a backup before you're trying to modify your partitions!

Some thoughts on Open Source Software

2016-02-18T14:00:00Z

TL;DR There's no alternative to OSS but we need to improve how we're dealing with it.

Hannes Preishuber recently wrote a blog post (in german language) about appreciation of work as well as quality and documentation of software nowadays.

While I agree with Hannes that someone's work has to be appreciated, I disagree with his assumptions that OSS is responsible for bad software quality and service / documentation in general.

Today a huge amount of the cloud infrastructure and services run on OSS and companies like MongoDb have build a business around their OSS products.

If quality and service wouldn't be warranted here, that business won't work.

On the other hand, from a developer perspective, OSS can become frustrating anyway:
Independently from the platform, be it Node.js / JavaScript or .NET, new OSS projects are born, gain huge adoption - and die.

The problem here is not that these projects die in general because there are several reasons for that.
One reason is, the community has decided to choose another OSS project as state of the art.
Another one is, the core maintainer has decided to no longer maintain the project and makes an official statement about that.
Some maintainers also look for a successor who maintains the project in the future so the project doesn't die at all.

The real problem in OSS are those projects which start, grow over time and then die slowly - or from an adopters perspective: they become zombies. Typical indications for a project dying slowly are unmerged pull requests, unanswered and unresolved issues and of course no further commits to at least update the projects own depedencies.

As said in the introduction, there are no (or only few alternatives) to OSS. Even typical enterprise developers use OSS these days.
All of our customers use OSS in some way and frameworks like Angular will push this trend forward.

When advising customers about using external dependencies (not only OSS) in their code base, we tell them to look for indicators of OSS zombie projects and have countermeasures on hand if a depedency is no longer maintained.

On the other hand, I came to the conclusion that OSS projects, especially the many smaller ones need to be handled in another way opposed to how they're handled nowadays.

If you look at Cassandra, Node.js or Microsoft .NET as OSS projects, they're all under the hood of a foundation which supports these projects. These foundations like Apache Foudation, Linux Foundation, or .NET Foundation provide guidance, mentoring as well as legal, technical and fincancial support.

But I think we should have another form of support or foundation in order to avoid zombie projects and respect criticism from people like Hannes.

After thinking about it for a while and talking to some fellows about it, here are my thoughts:

In general we should distinguish between the "ownership" of the project and the copyright / license for the code.
If you decide to start a new OSS project on GitHub, GitLab, BitBucket or whereever, beside selecting a license for your project, you should be able to transfer the ownership of the project to sort of a "registry".

This registry should provide these features:

The initiator of the project becomes the "general manager" of the project and can work on the project as we all used to work on OSS as before.
But in addition to that, the registry provides the following features:

A general manager can resign itself if he doesn't want to maintain to project any longer. The project then is in a pool of projects "looking for new general manager". Other people can apply for that role and take over projects in a governed and transparent way. Community could even vote the next general manager if more persons apply as general manager for a particular project.
A general manager can be resigned by the registry which might sound frightening at a first sight. But I think there are several advantages. For example, if a core maintainer doesn't even respond to pull requests or issues in some manner in a reasonable time, he might get warnings from the registry. After a specific number of warnings he could be resigned by the registry and the project gets in the pool as described above.
Projects can have proxies. If the general manager is temporarily not able to maintain the project, the proxy can maintain the project during that period.

Some might argue that this is way to much overhead but I'm sure I'm not the first who ran into zombie projects and the bigger your codebase is or if you're maintaining a huge number of critical projects for your customers, you don't want to kill the living deads in your code every now and then. And your customers should not have to pay for this problem.

Please let me know your thoughts about in the comments.

Debugging Node.js + TypeScript in a Docker Container with WebStorm

2016-04-06T11:00:00Z

In order to be able to debug Node.js with TypeScript in a Docker container (or in general: debug remote) using WebStorm, compilerOptions in your tsconfig.json need to contain inlineSources and inlineSourceMap being set to true.

So your tsconfig.json might look like this:

{
  "compilerOptions": {
    "outDir": "build",
    "inlineSources": true,
    "inlineSourceMap": true
  },
  "include": [
    "src/**/*"
  ],
  "exclude": [
    "**/*.spec.ts"
  ]
}

Getting all registered routes in express.js

2016-04-06T21:45:00Z

To get all routes registered in express.js, this snippet gets the work done:

const routes = [];

app._router.stack.forEach((middleware) => {
  if (middleware.route) {
    routes.push(
      `${Object.keys(middleware.route.methods)} -> ${middleware.route.path}`
    );
  }
});

console.log(JSON.stringify(routes, null, 2));

Possible result:

[
  "post -> /customers"
  "put -> /customers/:id",
  "delete -> /customers/:id"
]

Deploying a private, secured Docker Registry within 15 minutes

2016-04-08T18:45:00Z

After using Docker in development, you might want to put your application into production. Depending on your need, you might not want to push your private Docker images for your application to the Docker Hub, but have a private registry instead.

Docker has been providing the private registry on GitHub for a long time and it works pretty well. The downside is that it doesn't provide security features like RBAC.

That's where 3rd party solutions kick in.

We've been evaluating several solutions like AWS EC2 Container Registry (ECR) and others.
In the end, we're now running on Harbor, an Open Source registry server from VMware build around the aforementioned Docker registry.

Harbor is being developed in Golang and provides these key features:

Access Control: RBAC (Role Based Access Control) is provided. User management can be integrated with existing enterprise identity services like AD/LDAP.
Audit: All access to the registry are logged and can be used for audit purpose.
GUI: User friendly single-pane-of-glass management console.
Project based approach to separate images and access to them

First, here are some screenshots from harbor, starting with the admin dashboard:

Beside user self registration (can be turned off), the Admin can invite users:

Admins can create projects:

You can see all images for a particular project:

The Harbor User Guide shows some more screenshots.

The goal of this post is to get a Harbor instance running on DigitalOcean with HTTPS enabled using Docker Machine.

I'm assuming that you're familiar with Docker Machine basics and have it up and running. Furthermore, you'll need to have the Docker engine and Docker Compose installed which are required by Harbor for deployment.
And because we want to enable HTTPS, you should have grabbed a certificate from DigiCert or somewhere else.

First, clone the latest Harbor version from GitHub:

$ git clone git@github.com:vmware/harbor.git

Inside the Deploy folder there are several configuration options within the harbor.cfg file.

There are two options you have to configure at a minimum:

hostname = harbor.yourdomain.com
ui_url_protocol = https

Inside the Deploy/config/nginx folder there are two nginx configuration files named nginx.conf and nginx.https.conf.

The file being used by Harbor is nginx.conf. Because we want to use HTTPS, we need to get Harbor use nginx.https.conf:

$ mv nginx.conf nginx.conf.bak
$ cp nginx.https.conf nginx.conf

Then we have to modify the new nginx.conf and replace the two occurrences of harbordomain.com with our own Harbor URI, e.g. harbor.yourdomain.com.

Regarding the certificate, there a two options: Use the cert filename from DigiCert (in my case) and the server.key file and modify the nginx.conf accordingly or rename the certificate to harbordomain.crt.

Either case, you have to copy the cert file and the key file from your Certificate Signing Request to the Deploy/config/nginx/cert folder.

The SSL settings within the nginx.conf should look like this:

# SSL
ssl_certificate /etc/nginx/cert/harbor_yourdomain_com.pem;
ssl_certificate_key /etc/nginx/cert/harbor_yourdomain_com.key;

Next, from the bash, run the following command within the Deploy folder:

$ ./prepare

This will copy the settings to their appropriate destinations.

With that done, lets create our Docker Machine instance for deployment. To create a DigitalOcean Droplet using Docker Machine, we need an API access token which can be created at the DigitalOcean Website (Azure or AWS are similar):

Copy your token and keep it safe, you won't see it again at the DigitalOcean website.

Now, back to the bash, we can create a Droplet using Docker Machine - make sure it has at least 2GB of RAM:

$ docker-machine create --driver digitalocean --digitalocean-access-token <yourtokenfromabove> --digitalocean-size 2GB harbor.yourdomain.com

Docker Machine provides more options for the --driver like the region. Just read the Docker Machine Driver Documentation for more.

When the Droplet is up and running (this should take only a few seconds), activate that particular Docker Machine instance:

$ eval $(docker-machine env harbor.yourdomain.com)

Because we want to spin up the containers required by Harbor using Docker Compose, we have to copy the settings from the Deploy/config directory first to our Docker Machine instance.

First, get the absolute path to the Deploy directory (cd first into it):

$ echo $PWD

The result should be something like this:

/home//src/harbor/Deploy

Now we create the exact same absolute folder structure (including the config subfolder) inside the Docker Machine instance and copy the contents of our local Deploy/config folder into it:

$ docker-machine ssh harbor.ỳourdomain.com 'mkdir -p /home/<yourusername>/src/harbor/Deploy/config
$ docker-machine scp -r ./config harbor.yourdomain.com:$PWD

Next, build the container images using Docker Compose (inside the Deploy folder):

$ docker-compose build

And as a last step, we're spinning up our containers:

$ docker-compose up -d

Now you should be able to browse https://harbor.yourdomain.com:

And of course, you can start pushing and pulling Docker images to and from your own registry now!

After creating a new project (I'm using test here) and user as an Admin inside Harbor, you can push new images to Harbor like this:

$ docker tag customerservice:1.0.0 harbor.yourdomain.com/test/customerservice:1.0.0
$ docker login -u <username> -p <password> -e <email> harbor.yourdomain.com
$ docker push harbor.yourdomain.com/test/customerservice:1.0.0

And we're done!

As a side note: If you want to disable user self registration, apply this setting in harbor.cfg:

self_registration = off

P.S.: This post mostly is a combination of the Harbor Installation Guide and the Deploying Harbor using Docker Machine Guide (the latter I contributed to the Harbor project, so I didn't just copy existing stuff).

Debugging a ES6 Node.js application in a Docker container using Visual Studio Code

2016-04-08T21:45:00Z

Yesterday I just tried to debug an ES6 Node.js application using Visual Studio Code and noticed that I couldn't remote debug.

So I just asked on Twitter and got some replies from Erich Gamma and Andre Weinand today:

@alexzeitler_ @code pls see the remote debugging section here https://t.co/XoMlvRis5Z // @weinand
— ErichGamma (@ErichGamma) April 8, 2016

@alexzeitler_ @ErichGamma @code Sorry, but some changes from the release notes have not yet found their way into the doc.
— Andre Weinand (@weinand) April 8, 2016

@erichgamma @alexzeitler_ @code and here the section about node.js remote debugging: https://t.co/TbzNwjKX7y
— Andre Weinand (@weinand) April 8, 2016

As things didn't make it into official docs until now, I'll wrap it up here in a block post.

To keep things simple, this is our Node.js application:

const express = require('express');
const app = express();

app.get('/', (req, res) => {
    res.status(200).send('hello world');
})

app.listen(3000);

Add a jsconfig.json into the root of the project:

{
    "compilerOptions": {
        "target": "ES6",
        "module": "commonjs"
    }
}

Create a Dockerfile:

FROM node:4.2.3

EXPOSE 3000
EXPOSE 5858
COPY . /app
WORKDIR /app

RUN cd /app; npm install
CMD ["node", "--debug=5858","index.js"]

Create a launch.json (or create it by clicking the Debug button in VS Code):

{
	"version": "0.2.0",
	"configurations": [
		{
			"name": "Launch",
			"type": "node",
			"request": "launch",
			"program": "${workspaceRoot}/index.js",
			"stopOnEntry": false,
			"args": [],
			"cwd": "${workspaceRoot}",
			"preLaunchTask": null,
			"runtimeExecutable": null,
			"runtimeArgs": [
				"--nolazy"
			],
			"env": {
				"NODE_ENV": "development"
			},
			"externalConsole": false,
			"sourceMaps": false,
			"outDir": null
		},
		{
			"name": "Attach",
			"type": "node",
			"request": "attach",
			"port": 5858,
			"address": "localhost",
			"restart": false,
			"sourceMaps": false,
			"outDir": null,
			"localRoot": "${workspaceRoot}/",
			"remoteRoot": "/app/"
		}
	]
}

The important part in the launch.json is the Attach configuration, especially the localRoot and remoteRoot properties:

As our application on the host is in /index.js, ${workspaceRoot}/ is the correct setting.

As you can see in the Dockerfile, inside the container our app runs in the /app working directory.

So I've set the remoteRoot to /app/

Next, we can build our Docker image:

$ docker build -t hellovscode .

With that finished, we can run a container based on the image with port mappings for 3000 and 5858 activated:

$ docker run -d -p 3000:3000 -p 5858:5858 hellovscode

Next start the Attach Debug configuration in VS Code:

As you can see, I have already set a breakpoint.

Now, issue a request to http://localhost:3000/ - and we're remote debugging Node.js / ES6 in Docker Container using Visual Studio Code!

If you're using Docker-Machine, make sure you're using the IP address of the Docker Machine your container are running in.

You can get the IP address of the Docker Machine using:

$ docker-machine ip <machinename>

Use this IP address in the "address" property of your VS Code Attach configuration in the launch.json.

The source code including the Visual Studio Code Workspace Settings can be found here

Debugging mocha tests with Visual Studio Code when Node.js is installed using nvm

2016-04-09T15:00:00Z

In my development environments, I never install Node.j using apt-get but use nvm instead to be able to use multiple Node.js versions in parallel.

To be able to debug mocha tests using Visual Studio Code, I'm using this launch.json:

{
	"version": "0.2.0",
	"configurations": [
		{
			"name": "Debug Mocha tests",
			"type": "node",
			"request": "launch",
			"program": "${workspaceRoot}/node_modules/mocha/bin/_mocha",
			"stopOnEntry": false,
			"args": ["-t", "10000", "test/test.js"],
			"cwd": "${workspaceRoot}",
			"preLaunchTask": null,
			"runtimeExecutable": "/home/alex/.nvm/versions/node/v4.2.3/bin/node",
			"runtimeArgs": [
				"--nolazy"
			],
			"env": {
				"NODE_ENV": "development"
			},
			"externalConsole": false,
			"sourceMaps": false,
			"outDir": null
		}
	]
}

The important part is the runtimeExecutable which points Visual Studio Code to the Node.js version I've installed using nvm.

If you don't use this setting, you'll get Cannot launch target (reason: spawn node ENOENT).:

Also make sure to change the args to change the mocha timeout in order to avoid timeout errors in the debug console.

With that being done, hit F5 and debug your tests:

As promised, no timeout errors:

Debugging mocha tests in a Docker container using Visual Studio Code

2016-04-10T00:00:00Z

In a current Node.js / Docker customer project I had to debug some mocha tests because Docker containers use UTC and you know: that timezone stuff...

In the end, I was debugging my mocha tests using WebStorm and node-inspector inside the containers and got stuff running.

As I have been playing around with Visual Studio Code recently and debugging Node.js in Docker containers as well as debugging mocha tests (both using VS Code), this thought came up: "how would I be able to debug mocha tests using Visual Studio Code in Docker containers?"

In the end, it worked out to be pretty staight forwarded.

Make sure to have ES6 enabled in jsconfig.json for the sample code:

{
    "compilerOptions": {
        "target": "ES6",
        "module": "commonjs"
    }
}

First, I have a little express application inside ./index.js:

const express = require('express');
const app = express();

app.get('/', (req, res) => {
    res.status(200).send('hello world');
})

app.listen(3000);

This application isn't really required for our tests but my aforementioned scenario was like it. Furthermore we need a process that prevents our container from exiting after he has been started, so we'll stick with that little app.

Next, we have a Dockerfile:

FROM node:4.2.3

EXPOSE 3000
EXPOSE 5858
COPY . /app
WORKDIR /app

RUN cd /app; npm install
CMD ["node","index.js"]

As this post is about debugging mocha tests, here's our little test (./test/test.js) we want to debug inside the container:

const assert = require('assert');

describe('Truth', () => {
    it('should be told', (done) => {
        assert.equal(true, true)
        done()
    })
})

The idea of how I want to debug this test inside a Docker container is as follows:

Start the container
Run mocha inside the container with --debug-brk at port 5858 to wait for Visual Studio Code to attach to the debugger
Attach Visual Studio code and debug the test

There is another viable method:

Don't use our app in index.js
Call mocha with --debug-brk and port 5858 in the Dockerfile CMD
Start the container
Attach Visual Studio code and debug the test

As I don't want to have a container dedicated for debugging of mocha tests, I prefer the first version.

Starting the container consists of building the image and running the container. This can be easily automated using nodemon, grunt-watch or something similar. You could even use a Docker Volume and not restart the container at all.

Whatever automation you choose, here are the commands to build and run the container:

$ docker build -t vscodemocha .
$ docker run -d --name vscodemocha -p 3000:3000 -p 5858:5858 vscodemocha

With our container being up and running, we can configure Visual Studio Code to run mocha inside the container.

The Visual Studio Code attach Configuration allows to provide a preLaunchTask which is a task that can be defined inside the tasks configuration in tasks.json.

So we'll simply create a runmochaindocker task based on the bash command in tasks.json (inside the .vscode folder):

{
    "version": "0.1.0",
    "isShellCommand": true,
    "command": "bash",
    "args": [
        "-c"
    ],
    "tasks": [
        {
            "taskName": "runmochaindocker",
            "showOutput": "always",
            "suppressTaskName": true,
            "args": [
                "docker exec -i vscodemocha bash -c \"./node_modules/mocha/bin/mocha --debug-brk=5858 -t 10000 test/test.js\""
            ]
        }
    ]
}

Having that done, we're now referencing that task in the attach configuration in launch.json:

{
	"version": "0.2.0",
	"configurations": [
		{
			"name": "Attach to Mocha in Docker",
			"type": "node",
			"request": "attach",
			"port": 5858,
            "preLaunchTask": "runmochaindocker",
			"address": "localhost",
			"restart": false,
			"sourceMaps": false,
			"outDir": null,
			"localRoot": "${workspaceRoot}/",
			"remoteRoot": "/app/"
		}
	]
}

As already said, runmochaindocker now is defined as a preLaunchTask. And as already described in my recent post on debugging a Node.js app in a Docker container, I set localRoot and remoteRoot accordingly.

Guess what? We're done!

Just hit F5 now, and you'll get this:

Then, hit F5 again:

(To be honest, I'm not sure why the debugger breaks here - but we can ignore that).

Hit F5 one last time, and we're there: debugging our mocha test in a Docker container:

Happy debugging!

Deploying Ubuntu Mate Desktop as a developer environment in AWS EC2

2016-04-29T00:00:00Z

TL;DR: If you don't want to find out the solution by running over 40 Ubuntu installations with several desktop environments on AWS, read on.

On a current project the idea came up to put Ubuntu Desktop developer environments into AWS EC2 instead of local installations (VMs) and RDP into it.

If you have a Windows background, you would expect to just spin up a server and have a UI...

But with Ubuntu things get a little *cough* bit more complicated.

In general, there are several options:

Install an Ubuntu or Debian Server and install an Ubuntu Desktop environment onto it, then connect via VNC to it
Install an Ubuntu or Debian Server and install an Ubuntu Desktop environment onto it, then connect via RDP to it
Create an AMI based on an existing AMI
Create an AMI from scratch

Another option that sounds appealing won't work: Create a Windows Server VM, activate Hyper-V, install VMware Workstation or VirtualBox and just run your Ubuntu Desktop inside it.
The first two options won't work because you can't have nested Hypervisors in AWS EC2 and VirtualBox would only allow 32bit OS installations because of this constraint.

So, back to the viable options: First, I tried to install Ubuntu Server 14.04 from the official AWS AMI, install the XFCE or GNOME-Desktop on it as well as vncserver.
While it works in general, the VNC performance and quality is not acceptable in 2016 (I expect true color and reasonable screen resolutions) - especially with GNOME or more complex desktop environments.
Besides that, XFCE feels like late 90th:

So, lets head over to the next option - the one I ended up with:

Install Ubuntu Server from the official AWS EC2 AMI, put Ubuntu Mate desktop on it and RDP into it.
What sounds like a straight forward plan, ended up as a *interesting* journey.

I've chosen (read: learned to choose) Mate, because it is one of the environments that looks pretty nice but doesn't require 3D acceleration enabled which you just don't have in cloud environments (at least not in the general compute instances).

If you're ok with XCFE, the folks at AWS have created a manual for that (on which this post partially is based on).

First, create a AWS EC2 instance of your choice, enable inbound Port 3389 (RDP) in its security group settings and SSH into it.

Enabling Port 3389:

After that, install the latest updates:

sudo apt-get udpate
sudo apt-get upgrade
sudo apt-get dist-ugprade

Next, enable password authentication for sshd:

sudo vim /etc/ssh/sshd_config

Find the line PasswordAuthentication no and change it to PasswordAuthentication yes

Save the sshd_config and restart sshd:

sudo /etc/init.d/ssh restart

Next, create a password for your default ubuntu user:

sudo -i
passwd ubuntu

Then, create a user which you want to be your Desktop user, I'll use awsgui here:

sudo useradd -m awsgui
sudo passwd awsgui
sudo usermod -aG admin awsgui
sudo usermod -aG sudo awsgui
su - awsgui

After that, install the Ubuntu Mate desktop and xrdp:

export DEBIAN_FRONTEND=noninteractive
sudo apt-add-repository ppa:ubuntu-mate-dev/ppa
sudo apt-add-repository ppa:ubuntu-mate-dev/trusty-mate
sudo apt-get update && sudo apt-get upgrade
sudo apt-get install --no-install-recommends ubuntu-mate-core ubuntu-mate-desktop
sudo apt-get install mate-core mate-desktop-environment mate-notification-daemon
sudo apt-get install xrdp

Now, make Mate the default desktop environment for xrdp sessions (also for new users being created afterwards):

echo mate-session> ~/.xsession
sudo cp /home/awsgui/.xsession /etc/skel

Finally, we'll allow changing the host post port we can connect to (this allows reconnecting to an abandoned session):

sudo vim /etc/xrdp/xrdp.ini

Change port=-1 in the [xrdp1] section to port=ask-1.

With the changes done, restart xrdp:

sudo service xrdp restart

Now we're able to RDP into our AWS EC2 instance from Windows:

First, enter the public DNS entry (later on you'll assign an Elastic IP, of course) into the Windows Remote Desktop Client:

Next you should get the xrdp login screen were you enter your awsgui credentials and make sure sesman-Xvnc module is selected:

If everything went well, you should get this connection log:

After a second or two, you should also get the Ubuntu Mate desktop screen:

If you think we're done now: no.

Lets consider, we installed an EC2 instance with an SSD, that volume is mount to /mnt.

To make use of it, we need to chown it for the awsgui user - open a Terminal window by hitting <Ctrl><Alt><T> in the Mate environment. Then run:

sudo chown awsgui /mnt

Now, we can make use of /mnt.

Running software in the Mate environment

Here are some tips for running software in that environment.

Ubuntu Software Center

First of all, Ubuntu Software Center doesn't work due to some configuration errors I didn't get behind.
So if you have some nice .deb packages like Dropbox, just install them via Terminal:

sudo dpkg -i <package>.deb

Changing the timezone

If you want to change the timezone of your instance, you can't unlock and edit the setting in the UI.

Thus, you have to run sudo dpkg-reconfigure tzdata in Terminal and select the appropriate setting.

Dropbox

If you plan to install Dropbox, just download the .deb file and install it as described before.
You can start Dropbox using start dropbox -i to install the daemon.

After the installation you might see a weird or even no notification icon.
Just restart your EC2 instance and everything should be ok.

Restart / Shutdown via Mate

Speaking of restarting: You might notice that using the Mate logout / shutdown / restart feature won't end your RDP session. Just use sudo reboot or sudo shutdown now -h in Terminal.

Docker on `/mnt`

If you're running Docker and want to use the aforementioned volume /mnt (because otherwise it might eat up your small boot volume) for the images and volumes, just change your Docker config:

sudo vim /etc/default/docker

Add this line or change / extend your DOCKER_OPTS entry as follows:

DOCKER_OPTS="-g /mnt/.docker"

Before you restart your Docker service, make sure to create the folder:

mkdir /mnt/.docker

Now restart Docker by running sudo service docker restart.

docker pull node:4.2.3 should pull Node 4.2.3 and put it to /mnt/.docker:

Visual Studio Code

It just doesn't work in xrdp environments as of now - even with the latest Insider build installed.

I guess working with the environment will show some more caveats and if I get them solved, I'll keep the solutions posted.

I also would be happy if you share further tips in the comments.

Deploying Ubuntu Mate Desktop as a developer environment in a Azure VM

2016-06-01T00:00:00Z

TL;DR: While boring looking XFCE installation on Ubuntu Server is shown everywhere, this post shows you how to get a nice Mate Desktop on Ubuntu in Azure up and running and RDP into it.

In Windows Server environments you just spin up a Server and have a GUI, install Visual Studio and start developing.

But with Ubuntu Server things get a little bit more complicated.

I've chosen (read: learned to choose) Mate Desktop, because it is one of the environments that looks pretty nice but doesn't require 3D acceleration enabled which you just don't have in cloud environments (at least not in the general compute instances).

First, create a Azure VM instance of your choice with a username and password, enable inbound Port 3389 (RDP) in its NIC security group settings and SSH into it.

Enabling Port 3389 for RDP, first select "Network interfaces":

Next, select the "Network security group":

Select "Inbound security rules":

You'll see the default inbound rules:

Add a new rule for RDP via port 3389:

Check the updated inbound rules:

After that, install the latest updates:

sudo apt-get udpate
sudo apt-get upgrade
sudo apt-get dist-ugprade

With that done, install the Ubuntu Mate desktop and xrdp:

export DEBIAN_FRONTEND=noninteractive
sudo apt-add-repository ppa:ubuntu-mate-dev/ppa
sudo apt-add-repository ppa:ubuntu-mate-dev/trusty-mate
sudo apt-get update && sudo apt-get upgrade
sudo apt-get install --no-install-recommends ubuntu-mate-core ubuntu-mate-desktop
sudo apt-get install mate-core mate-desktop-environment mate-notification-daemon
sudo apt-get install xrdp

Now, make Mate the default desktop environment for xrdp sessions (also for new users being created afterwards):

echo mate-session> ~/.xsession
sudo cp ~/.xsession /etc/skel

Finally, we'll allow changing the host post port we can connect to (this allows reconnecting to an abandoned session):

sudo vim /etc/xrdp/xrdp.ini

Change port=-1 in the [xrdp1] section to port=ask-1.

With the changes done, restart xrdp:

sudo service xrdp restart

Now we're able to RDP into our Azure VM from Windows:

You should get the xrdp login screen were you enter your users credentials and make sure sesman-Xvnc module is selected:

If everything went well, you should get this connection log:

After a second or two, you should also get the Ubuntu Mate desktop screen:

If you think we're done now: no.

Running software in the Mate environment

Here are some tips for running software in that environment.

Ubuntu Software Center

First of all, Ubuntu Software Center doesn't work due to some configuration errors I didn't get behind.
So if you have some nice .deb packages like Dropbox, just install them via Terminal:

sudo dpkg -i <package>.deb

Changing the timezone

If you want to change the timezone of your instance, you can't unlock and edit the setting in the UI.

Thus, you have to run sudo dpkg-reconfigure tzdata in Terminal and select the appropriate setting.

Dropbox

If you plan to install Dropbox, just download the .deb file and install it as described before.
You can start Dropbox using start dropbox -i to install the daemon.

After the installation you might see a weird or even no notification icon.
Just restart your Azure VM and everything should be ok.

If you still experience issues, you can also install caja-dropbox with is optimizied for the caja file manager of MATE.

Restart / Shutdown via Mate

Speaking of restarting: You might notice that using the Mate logout / shutdown / restart feature won't end your RDP session. Just use sudo reboot or sudo shutdown now -h in Terminal.

Visual Studio Code / ATOM

It just doesn't work in xrdp environments as of now - even with the latest Insider build installed.

Today I published a gist which describes a fix to get VS Code / ATOM in Ubuntu via RDP working.

I would be happy if you share further tips in the comments.

Mongoose toObject and toJSON transform behavior with sub-documents

2016-06-08T00:00:00Z

Mongoose supports two Schema options to transform Objects after querying MongoDb: toObject and toJSON.

In general you can access the returned object in the transform method toObject or toJSON as described in the docs.

Where things get interesting is when you're trying to use sub-documents and want them to be not touched by the transform method of the root or parent document.

After playing around with toObject and toJSON transforms with sub-documents, I observed the behaviors described as follows.

First, our two schemas for context:

User.js:

'use strict';
const mongoose = require('mongoose');

let UserSchema = new mongoose.Schema({
    name: String
});

module.exports = mongoose.model("User", UserSchema);

Post.js:

'use strict'
let mongoose = require('mongoose');

let PostSchema = new mongoose.Schema({
  title: String,
  postedBy: {
    type: mongoose.Schema.Types.ObjectId,
    ref: 'User'
  },
  comments: [{
    text: String,
    postedBy: {
      type: mongoose.Schema.Types.ObjectId,
      ref: 'User'
    }
  }]

}, {
  toObject: {
    transform: function (doc, ret) {
      delete ret._id;
    }
  },
  toJSON: {
    transform: function (doc, ret) {
      delete ret._id;
    }
  }
});

module.exports = mongoose.model("Post", PostSchema);

As you can see, mongoose.Schema accepts a second parameter which contains the definitions for toObject and toJSON.

Next, let's use both Schemas in simple sample:

app.js

'use strict';
require("./database");

let User = require('./User'),
  Post = require('./Post');


let alex = new User({
  name: "Alex"
});

let joe = new User({
  name: "Joe"
});

alex.save();
joe.save();

let post = new Post({
  title: "Hello World",
  postedBy: alex._id,
  comments: [{
    text: "Nice post!",
    postedBy: joe._id
  }, {
    text: "Thanks :)",
    postedBy: alex._id
  }]
});

post.save(function (error) {
  if (!error) {
    Post.find({})
      .populate('postedBy')
      .populate('comments.postedBy')
      .exec(function (error, posts) {
        console.log(posts)
      })
  }
});

The result is as follows:

[ { comments: [ [Object], [Object] ],
    __v: 0,
    postedBy: { __v: 0, name: 'Alex' },
    title: 'Hello World' } ]

As you can see, _id from both Post and User get removed by the toObject transformation.

Next, we'll replace console.log(posts) as follwos:

console.log(JSON.stringify(posts, null, '\t'));

The result is the following JSON:

[
	{
		"title": "Hello World",
		"postedBy": {
			"_id": "57588aa352559c927c98c793",
			"name": "Alex",
			"__v": 0
		},
		"__v": 0,
		"comments": [
			{
				"text": "Nice post!",
				"postedBy": {
					"_id": "57588aa352559c927c98c794",
					"name": "Joe",
					"__v": 0
				},
				"_id": "57588aa352559c927c98c797"
			},
			{
				"text": "Thanks :)",
				"postedBy": {
					"_id": "57588aa352559c927c98c793",
					"name": "Alex",
					"__v": 0
				},
				"_id": "57588aa352559c927c98c796"
			}
		]
	}
]

The _id from Post gets removed while _id from User remains.

The same behavior can be seen when we call toJSON explicitly:

 let json = posts.map(function (p) {
  return p.toJSON()
});
console.log(json)

Result:

[ { title: 'Hello World',
    postedBy: { _id: 57588c7ebf8340cc859660e1, name: 'Alex', __v: 0 },
    __v: 0,
    comments: [ [Object], [Object] ] },
  { title: 'Hello World',
    postedBy: { _id: 57588c97fc8232548659e6d4, name: 'Alex', __v: 0 },
    __v: 0,
    comments: [ [Object], [Object] ] } ]

So it looks like toObject is being applied to sub-documents while toJSON is not. And this is different from what the documentation says:

Transforms are applied only to the document and are not applied to sub-documents.

The other option is that I'm wrong but questions on stackoverflow show it really might be the documentation.

Non-Interactive Azure Resource Manager (ARM) login

2016-06-25T00:00:00Z

Azure Resource Manager allows you to deploy, manage, and monitor all of the resources for your solution as a group, rather than handling these resources individually.

TL;DR from the docs:

With Resource Manager, you can create a simple template (in JSON format) that defines deployment and configuration of your application. This template is known as a Resource Manager template and provides a declarative way to define deployment. By using a template, you can repeatedly deploy your application throughout the app lifecycle and have confidence your resources are deployed in a consistent state.

Before you can deploy a resource group using PowerShell, you have to login using the Login-AzureRmAccount command.

By default, this opens a dialog where you can enter your Azure credentials:

This is ok if you are working with ARM on your local machine, but you don't want this behavior on your CI-Server for example.

Luckily, the Login-AzureRmAccount command also accepts an -Credential parameter which is an object consisting of your username and password.

The following PowerShell commands show how to create this object:

$accountName ="your account name"
$password = ConvertTo-SecureString "your password" -AsPlainText -Force
$credential = New-Object System.Management.Automation.PSCredential($accountName, $password)

Now you can login using the Login-AzureRmAccount command like this:

Login-AzureRmAccount -Credential $credential

If you're providing username and password using environment variables for example, you can set $accountName and password using these commands:

$accountName = (get-item env:"ACCOUNTNAME").Value
$password = (get-item env:"PASSWORD").Value

Happy deployment!

Fixing Chrome 58+ [missing_subjectAltName] with openssl when using self signed certificates

2017-04-23T00:00:00Z

Since version 58, Chrome requires SSL certificates to use SAN (Subject Alternative Name) instead of the popular Common Name (CN), thus CN support has been removed.
If you're using self signed certificates (but not only!) having only CN defined, you get an error like this when calling a website using the self signed certificate:

Here's how to create a self signed certificate with SAN using openssl

First, lets create a root CA cert using createRootCA.sh:

#!/usr/bin/env bash
mkdir ~/ssl/
openssl genrsa -des3 -out ~/ssl/rootCA.key 2048
openssl req -x509 -new -nodes -key ~/ssl/rootCA.key -sha256 -days 1024 -out ~/ssl/rootCA.pem

Next, create a file createselfsignedcertificate.sh:

#!/usr/bin/env bash
sudo openssl req -new -sha256 -nodes -out server.csr -newkey rsa:2048 -keyout server.key -config <( cat server.csr.cnf )

sudo openssl x509 -req -in server.csr -CA ~/ssl/rootCA.pem -CAkey ~/ssl/rootCA.key -CAcreateserial -out server.crt -days 500 -sha256 -extfile v3.ext

Then, create the openssl configuration file server.csr.cnf referenced in the openssl command above:

[req]
default_bits = 2048
prompt = no
default_md = sha256
distinguished_name = dn
 
[dn]
C=US
ST=New York
L=Rochester
O=End Point
OU=Testing Domain
emailAddress=your-administrative-address@your-awesome-existing-domain.com
CN = localhost

Now we need to create the v3.ext file in order to create a X509 v3 certificate instead of a v1 which is the default when not specifying a extension file:

authorityKeyIdentifier=keyid,issuer
basicConstraints=CA:FALSE
keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
subjectAltName = @alt_names

[alt_names]
DNS.1 = localhost

In order to create your cert, first run createRootCA.sh which we created first. Next, run createselfsignedcertificate.sh to create the self signed cert using localhost as the SAN and CN.

After adding the rootCA.pem to the list of your trusted root CAs, you can use the server.key and server.crt in your web server and browse https://localhost using Chrome 58 or later:

You can also verify your certificate to contain the SAN by calling

openssl x509 -text -in server.crt -noout

This should look like this:

Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number: 17237690484651272016 (0xef38942aa5c52750)
    Signature Algorithm: sha256WithRSAEncryption
        Issuer: C=US, ST=New York, L=Rochester, O=End Point, CN=localhost/your-administrative-address@your-awesome-existing-domain.com
        Validity
            Not Before: Apr 23 16:07:38 2017 GMT
            Not After : Sep  5 16:07:38 2018 GMT
        Subject: C=US, ST=New York, L=Rochester, O=End Point, OU=Testing Domain/emailAddress=your-administrative-address@your-awesome-existing-domain.com, CN=localhost
        Subject Public Key Info:
            Public Key Algorithm: rsaEncryption
                Public-Key: (2048 bit)
                Modulus:
                    00:b2:e3:bd:ed:28:04:85:ea:75:ee:d2:82:e1:eb:
                    f5:5f:7f:cf:7e:cb:70:de:86:9f:75:7c:f3:71:e7:
                    da:16:fb:bc:1f:89:bc:47:08:77:ca:33:20:f1:c1:
                    9e:e3:20:8d:89:14:7e:c1:0a:12:d2:59:24:56:9b:
                    77:90:5f:69:d1:a5:f1:00:38:93:1b:a7:75:f1:33:
                    e2:da:dc:32:a9:0a:85:7d:9a:20:81:ca:20:ee:86:
                    ce:e2:a0:52:d2:ab:11:34:e5:52:99:3a:81:c6:9f:
                    6b:0f:6a:02:2b:38:a6:84:c9:ba:fa:9b:ef:0a:89:
                    22:4b:79:86:3c:bd:44:a5:54:fb:cf:4d:8b:d1:44:
                    03:35:22:de:69:77:c8:fa:4d:c6:01:25:08:9f:4d:
                    a9:79:7a:aa:ca:03:b6:e4:51:57:22:27:5f:a7:12:
                    11:f3:e6:00:29:f6:58:be:2c:aa:09:e4:06:45:d9:
                    3f:75:a7:f0:75:bd:2b:a6:bb:6d:ad:93:bb:b9:1d:
                    d7:75:39:4e:9b:1d:0e:39:cc:17:74:88:f7:e2:b7:
                    85:12:96:e0:cb:42:56:d0:11:e0:84:86:e5:14:a5:
                    f2:6d:43:5d:f9:59:ae:61:7f:01:ae:95:b8:92:27:
                    1d:1c:02:d7:ad:fb:ee:f6:25:38:60:c8:41:20:17:
                    80:69
                Exponent: 65537 (0x10001)
        X509v3 extensions:
            X509v3 Authority Key Identifier: 
                keyid:5A:8D:89:64:BD:F2:3E:C2:D7:7B:BE:17:84:F4:29:E8:C5:32:35:34

            X509v3 Basic Constraints: 
                CA:FALSE
            X509v3 Key Usage: 
                Digital Signature, Non Repudiation, Key Encipherment, Data Encipherment
            X509v3 Subject Alternative Name: 
                DNS:localhost
    Signature Algorithm: sha256WithRSAEncryption
         27:1d:d6:84:50:33:d2:ff:b1:06:9b:fa:f1:40:7d:47:11:bc:
         f7:80:fd:26:87:0e:91:9f:14:be:1f:1d:9b:32:d1:fb:d6:8d:
         af:30:8a:88:38:8c:1c:bf:77:98:8e:cd:06:48:82:fa:09:b9:
         3c:0d:38:c4:a0:da:b7:4d:f5:81:5f:5a:76:04:61:f8:c2:1a:
         17:ad:56:7c:72:ba:f6:65:7f:7f:e7:5e:b2:34:ba:13:23:57:
         84:f1:c5:ca:dd:5b:55:69:95:71:44:4a:30:53:61:5c:ad:47:
         d8:9c:d5:a2:1b:18:2d:e1:19:35:3e:3f:b2:7e:fd:bf:f3:d0:
         45:dc:f5:57:f0:1b:cd:70:1b:e0:34:de:27:98:89:b4:a5:25:
         a5:6c:29:c3:89:a6:a5:c5:4d:f5:45:3b:47:8e:13:45:23:07:
         5e:d6:59:0d:96:c6:a3:f0:c5:3d:ee:a8:ad:36:96:43:13:a1:
         b8:55:f6:c7:10:7e:8f:5d:09:ef:61:17:2a:9c:3b:50:28:c8:
         e3:8d:a6:34:06:50:d4:3e:d5:17:ea:7d:31:97:d3:ee:df:b5:
         23:66:5e:22:b7:e4:fa:36:4f:9a:d5:f0:a3:f9:b4:2b:27:02:
         0b:41:94:d1:a1:f7:1b:2c:7e:74:e6:14:c3:b5:67:15:d2:ca:
         02:77:57:a6

Watch for this line Version: 3 (0x2) as well as X509v3 Subject Alternative Name: (and below).

Happy self signing!

Accessing an HTTP API running on your MacBook in a Docker container from your iPhone/iPad using dnsmasq

2017-04-23T00:00:00Z

Please consider the following scenario:

On my MacBook Pro I want to access a web application (SPA/PWA) and an API both running in Docker containers behind another nginx Docker container (reverse proxy managing SSL) from an iOS device.

So I have:

1 iOS device having IP 192.168.178.77
1 MacBook Pro having IP 192.168.178.64
1 Docker container running nginx having two server_name settings: app.dev and api.dev, both using self-signed SSL certificates.

The challenge: the're no option in the local Router to point DNS entries to 192.168.178.64.

/etc/hosts has these entries:

192.168.178.64 app.dev
192.168.178.64 api.dev

The easiest solution I've found is to use dnsmasq running in a Docker container.

So what is dnsmasq?

Dnsmasq is a lightweight, easy to configure, DNS forwarder and DHCP server. It is designed to provide DNS and optionally, DHCP, to a small network. It can serve the names of local machines which are not in the global DNS. The DHCP server integrates with the DNS server and allows machines with DHCP-allocated addresses to appear in the DNS with names configured either in each host or in a central configuration file. Dnsmasq supports static and dynamic DHCP leases and BOOTP/TFTP for network booting of diskless machines

source

In order to start dnsmasq in Docker container, simply run this command:

docker run \
	--name dnsmasq \
	-d \
	-p 53:53/udp \
	-p 5380:8080 \
	-v /opt/dnsmasq.conf:/etc/dnsmasq.conf \
	--log-opt "max-size=100m" \
	-e "USER=foo" \
	-e "PASS=bar" \
	jpillora/dnsmasq

This will run dnsmasq mapping a configuration from /opt/dnsmasq.conf into the container.

Make sure /opt/dnsmsq.conf at least contains this line:

address=/dev/192.168.178.64

This will route all traffic to *.dev to 192.168.178.64.

dnsmasq will also inspect your local /etc/hosts file and route traffic appropriately.

It also provides a simple UI where you can verify your hosts file got hooked up correctly: Just browse to http://localhost:5380 and enter the credentials foo and bar from the docker run command above.

The UI output should look like this:

[webproc] 2017/04/23 18:35:54 loaded config files changes from disk
[webproc] 2017/04/23 18:35:54 agent listening on http://0.0.0.0:8080...
dnsmasq: started, version 2.76 cachesize 150
dnsmasq: compile time options: IPv6 GNU-getopt no-DBus no-i18n no-IDN DHCP DHCPv6 no-Lua TFTP no-conntrack ipset auth no-DNSSEC loop-detect inotify
dnsmasq: reading /etc/resolv.conf
dnsmasq: using nameserver 192.168.65.1#53
dnsmasq: read /etc/hosts - 7 addresses

The next step is to update the DNS settings on the iOS and macOS devices.
The iOS device has to point to the IP address of the macOS device:

The macOS device has to point to itself:

Click "Advanced...", then select "DNS":

The last step is to call the https://app.dev and https://api.dev URIs on the iOS device and confirm the SSL warnings.

Other solutions to this seem to be http://xip.io/ or http://nip.io/ but I didn't try them...

Happy developing!

Getting started with CQRS

2018-04-11T21:45:00Z

CQRS and Event Sourcing have been there for a while now but especially in 2017 and the first months of 2018 we can see a rapid growth of inquires for CQRS based applications — why is this?

Many cloud based applications are built following the pattern of Microservices and are publishing or consuming events for integration purposes.

“The New Stack” recently released the article “Microservices: It’s All About the Events” and I want to quote this paragraph from the post:

“One of the key things about distributed systems is that you have a whole bunch of independent control loops responsible for their own processing,” she said. One of the favored concepts in this space is Command Query Responsibility Segregation (CQRS), which separates the channels for inserting data into a data store from the channel of querying that data, so that the performance of one is not dependent on another."

At PDMLab, we’re building several SaaS solutions applying the CQRS pattern and recently I’ve been asked, how I got started with CQRS.

Instead of repeating this answer over and over again, I decided to share my resources, that helped me getting into CQRS a few years ago, in this post.

First of all - of course - some videos from Greg Young, who came up with the definition of CQRS.

Greg Young also has a simple CQRS sample on GitHub: [https://github.com/gregoryyoung/m-r](https://github.com/gregoryyoung/m-r)

Several blog posts to get started with CQRS can be found at https://cqrs.wordpress.com/

A book, which helped me getting into CQRS was "CQRS" by Mark Nijhof: https://cqrs.wordpress.com/

Another video worth watching is "Eventually Consistent Distributed Systems with Node.js":

If you're looking for a more complete implementation of a sample application, you should have a look at the CQRS post series from Matthew Jones here (posts) and here (code).

The samples from Matthew are based on CQRSLite, a CQRS framework for .NET Standard which we're using as well.

If you're looking for a CQRS framework for Node.js, you should have a look at wolkenkit.

If you're around in Vancouver these days, you also should attend Lestercon where Adaptech will open source some of their Microservices / CQRS stacks and toolings.

Running ASP.NET Core on minikube

2018-11-13T11:00:00Z

There are a ton of managed Kubernetes services available today (and for sure even more tomorrow) to run your ASP.NET Core application.

If you want to run k8s locally you can spin up a whole cluster manually. Another solution is to use minikube.

So, what is minikube exactly?

Minikube is a tool that makes it easy to run Kubernetes locally. Minikube runs a single-node Kubernetes cluster inside a VM on your laptop for users looking to try out Kubernetes or develop with it day-to-day.

https://kubernetes.io/docs/setup/minikube/

Installing minikube

In order to be able to install minikube you need to have a Hypervisor like VirtualBox (Linux) or VMWare Fusion (macOS) installed. (This post won’t cover Windows btw.).

After installing your Hypervisor of choice, you have to install minikube

On macOS

curl -Lo minikube https://storage.googleapis.com/minikube/releases/v0.30.0/minikube-darwin-amd64 && chmod +x minikube && sudo cp minikube /usr/local/bin/ && rm minikube

On Linux (Ubuntu 18.04 here)

curl -Lo minikube https://storage.googleapis.com/minikube/releases/v0.30.0/minikube-linux-amd64 && chmod +x minikube && sudo cp minikube /usr/local/bin/ && rm minikube

Installing kubectl

In order to manage your k8s cluster or minikube, you need a command line tool named kubectl.

On macOS

brew install kubernetes-cli

On Linux (Ubuntu 18.04 here)

sudo apt-get update && sudo apt-get install -y apt-transport-https
curl -s https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key add -
echo "deb http://apt.kubernetes.io/ kubernetes-xenial main" | sudo tee -a /etc/apt/sources.list.d/kubernetes.list
sudo apt-get update
sudo apt-get install -y kubectl

Running minikube

Its as simple as typing minikube start into your terminal. And guess what? minikube stop will stop it 😉.

Dockerizing ASP.NET Core

Next, we need some ASP.NET Core Code running in a Docker Container, so lets spin up JetBrains Rider and create a new Web API project for example:

The default code in Startup.cs is fine here:

public class Startup
{
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public IConfiguration Configuration { get; }

    // This method gets called by the runtime. Use this method to add services to the container.
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);
    }

    // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
        app.UseMvc();
    }
}

The default ValuesController is fine as well:

[Route("api/[controller]")]
[ApiController]
public class ValuesController : ControllerBase
{
    // GET api/values
    [HttpGet]
    public ActionResult<IEnumerable<string>> Get()
    {
        return new string[] {"value1", "value2"};
    }

    // GET api/values/5
    [HttpGet("{id}")]
    public ActionResult<string> Get(int id)
    {
        return "value";
    }

    // POST api/values
    [HttpPost]
    public void Post([FromBody] string value)
    {
    }

    // PUT api/values/5
    [HttpPut("{id}")]
    public void Put(int id, [FromBody] string value)
    {
    }

    // DELETE api/values/5
    [HttpDelete("{id}")]
    public void Delete(int id)
    {
    }
}

Next, we need a Dockerfile in our project:

You can just grab the sample from the official Docker docs.

FROM microsoft/dotnet:sdk AS build-env
WORKDIR /app

# Copy csproj and restore as distinct layers
COPY *.csproj ./
RUN dotnet restore

# Copy everything else and build
COPY . ./
RUN dotnet publish -c Release -o out

# Build runtime image
FROM microsoft/dotnet:aspnetcore-runtime
WORKDIR /app
COPY --from=build-env /app/out .
ENTRYPOINT ["dotnet", "HelloNetCoreOnK8s.dll"]

Make sure to change the second param of the ENTRYPOINT array to the name of your DLL.

Next, build your image:

docker build -t hello-netcore-k8s .

You should get a result similar to this:

Sending build context to Docker daemon  1.185MB
Step 1/10 : FROM microsoft/dotnet:sdk AS build-env
 ---> 6baac5bd0ea2
Step 2/10 : WORKDIR /app
 ---> Using cache
 ---> 8b1b0606dfc8
Step 3/10 : COPY *.csproj ./
 ---> Using cache
 ---> 987d3ba17281
Step 4/10 : RUN dotnet restore
 ---> Using cache
 ---> 829018788c05
Step 5/10 : COPY . ./
 ---> 60d4d75c8825
Step 6/10 : RUN dotnet publish -c Release -o out
 ---> Running in 3e13616e9438
Microsoft (R) Build Engine version 15.8.169+g1ccb72aefa for .NET Core
Copyright (C) Microsoft Corporation. All rights reserved.

  Restoring packages for /app/HelloNetCoreOnK8s.csproj...
  Generating MSBuild file /app/obj/HelloNetCoreOnK8s.csproj.nuget.g.props.
  Generating MSBuild file /app/obj/HelloNetCoreOnK8s.csproj.nuget.g.targets.
  Restore completed in 1.68 sec for /app/HelloNetCoreOnK8s.csproj.
  HelloNetCoreOnK8s -> /app/bin/Release/netcoreapp2.1/HelloNetCoreOnK8s.dll
  HelloNetCoreOnK8s -> /app/out/
Removing intermediate container 3e13616e9438
 ---> e0edd75b100e
Step 7/10 : FROM microsoft/dotnet:aspnetcore-runtime
 ---> 1fe6774e5e9e
Step 8/10 : WORKDIR /app
 ---> Using cache
 ---> 6c95530f2566
Step 9/10 : COPY --from=build-env /app/out .
 ---> 34932a25e3b6
Step 10/10 : ENTRYPOINT ["dotnet", "HelloNetCoreOnK8s.dll"]
 ---> Running in 599e41e2537f
Removing intermediate container 599e41e2537f
 ---> e24c6efee7d4
Successfully built e24c6efee7d4
Successfully tagged hello-netcore-k8s:latest

Hello k8s

In order to create a k8s deployment, we need a yaml file which specifies what should be deployed in minikube.

Itshould be placed in our project as well:

This is the content of the deployment.yaml

apiVersion: extensions/v1beta1
kind: Deployment
metadata:
  name: hello-netcore-k8s
spec:
  replicas: 3
  template:
    metadata:
      labels:
        app: hello-netcore-k8s
    spec:
      containers:
        - name: hello-netcore-k8s
          image: hello-netcore-k8s
          ports:
            - containerPort: 80

The important part for now is the spec/template/spec/containers:

name specifies the name of the containers and image specifies the name of the image the containers should be created from — this obviously is the name of the image we created recently.

So lets create that deployment now using kubectl:

kubectl create -f deployment.yaml

Now check if the deployment has suceeded:

kubectl get deployments

The result will look similar to this:

Well... shouldn’t it be available? Lets dig a bit deeper and check the pods:

kubectl get pods

Looks like we have a problem here. Seems minikube doesn’t know about our recently created image 🤔.

The reason is that the Docker daemon in minikube doesn’t know about our Docker daemon on our Linux/macOS host.

But there’s a simple solution for that - we can share the context using this command:

eval $(minikube docker-env)

You can stop sharing the context using eval $(minikube docker-env -u).

Another solution would have been to push the image to the official Docker hub but we want to stay local for this sample.

Now we have to build our image again because of the different context — remember how to do it?

docker build -t hello-netcore-k8s .

Also we have to add the imagePullPolicy: Never to our deployment.yaml file:

apiVersion: extensions/v1beta1
kind: Deployment
metadata:
  name: hello-netcore-k8s
spec:
  replicas: 3
  template:
    metadata:
      labels:
        app: hello-netcore-k8s
    spec:
      containers:
        - name: hello-netcore-k8s
          imagePullPolicy: Never # <-- here we go!
          image: hello-netcore-k8s
          ports:
            - containerPort: 80

This ensures that the Docker daemon doesn’ t try to pull unknown images from the Docker registry.

So… lets fire up our deployment again:

kubectl create -f deployment.yaml

Validating the deployment using kubectl get deployments looks much better now:

Also the result of kubectl get pods is much better now:

Accessing the Application using a Service

So you might ask yourself: how do I access the application now?

In k8s and minikube as well, you have to create a service to expose the application to a public IP/Port. If you’ re running your application in a managed k8s environment at your cloud provider of choice, the type of the service to expose your application is likely to be a LoadBalancer. When using minikube, the only service type available is nodePort.

The command to expose your application using a nodePort, is this:

kubectl expose deployment hello-netcore-k8s --type=NodePort

The result should be this:

service/hello-netcore-k8s exposed

So, at which IP and Port has it been exposed? When using minikube, you have to use this command (this is different when using managed k8s):

minikube service hello-netcore-k8s --url

You’ll get an output like this:

http://192.168.99.100:31422

Now lets call our ASP.NET Core API via http get 192.168.99.100:31422/api/values (I’m using HTTPie here, you can choose your preferred tool here — maybe Postman):

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Tue, 13 Nov 2018 21:30:33 GMT
Server: Kestrel
Transfer-Encoding: chunked[
    "value1",
    "value2"
]

Yay! We’re done!

But wait — why are we running on port 31442 and not port 80?

The reason for that is the default configuration of minikube which provides a Port range between 30000–32767 for services and by creating a service using the command from above a random port is picked from that pool.

We should fix this, right?

First, delete all services and deployments in minikube:

kubectl delete service hello-netcore-k8s
kubectl delete deployment hello-netcore-k8s

Then stop minikube using minikube stop.

Now start minikube again using:

minikube start --extra-config=apiserver.service-node-port-range=80-30000

This will start minikube again, but with a Port range for services between 80-30000.

Now that we have port 80 available, how can we use it?

Add a services.yaml to your project with this content:

apiVersion: v1
kind: Service
metadata:
  name: hello-netcore-k8s 
  labels:
    app: hello-netcore-k8s 
spec:
  type: NodePort
  ports:
  - port: 80
    targetPort: 80
    nodePort: 80
    protocol: TCP
  selector:
    app: hello-netcore-k8s

This will assign port 80 to our service which is created using this command:

kubectl create -f services.yaml

Now, kubectl get services will result in:

As you can see, port 80 is used inside the Pod and mapped to the host port 80 as expected.

With that, http get 192.168.99.100/api/values again results in:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Tue, 13 Nov 2018 21:30:33 GMT
Server: Kestrel
Transfer-Encoding: chunked[
    "value1",
    "value2"
]

But this time it is clearly using port 80 - and now we’re done! 🙌

You can find the source code here.

Passing a ViewModel by Attribute to ASP.NET Core ViewComponents

2018-12-28T01:00:00Z

ASP.NET Core provides the concept of View components and the intro from the official docs reads quite straight forward:

View components are similar to partial views, but they're much more powerful. View components don't use model binding, and only depend on the data provided when calling into it. This article was written using ASP.NET Core MVC, but view components also work with Razor Pages.

Yet, it was a bit of confusing when trying to use View components with Tag Helpers and passing fragments of the parent view model to the View Component by attributes.

First, lets take a look at what we're building:

As you can see, there are two "sections" named "Books" and "Services" and both have child elements.

In order keep some structure and separate concerns, we don't want to render everything in the main view. The structure, we want to establish, is this:

Index-View of HomeController
 - PageSection ("Books")
  - SectionItems (List)
    - SectionItem (Title "Kubernetes")

Our complete ViewModel class structure is this - being loaded from a database or a headless CMS:

public class IndexViewModel
{
    public List<PageSection> Sections { get; set; }
}

public class PageSection
{
    public string Title { get; set; }
    public List<SectionItem> SectionItems { get; set; }
}

public class SectionItem
{
    public string Text { get; set; }
}

For the sake of simplicity, I'll just create it inline in HomeController.cs:

public class HomeController : Controller
{
    public IActionResult Index()
    {
        var indexViewModel = new IndexViewModel
        {
            Sections = new List<PageSection>
            {
                new PageSection
                {
                    Title = "Books",
                    SectionItems = new List<SectionItem>
                    {
                        new SectionItem { Text = "ASP.NET Core in Action" },
                        new SectionItem { Text = "Node.js in Action"}
                    }
                },
                new PageSection
                {
                    Title = "Services",
                    SectionItems = new List<SectionItem>
                    {
                        new SectionItem { Text = "ASP.NET Core Development"},
                        new SectionItem { Text = "Node.js Development"},
                        new SectionItem { Text = "Kubernetes"}
                    }
                }
            }
        };
        return View(indexViewModel);
    }
}

In the end, our Index.cshtml for the HomeController will be this:

@model IndexViewModel
@addTagHelper *, ViewComponentsSample

@foreach (var pageSection in Model.Sections)
{
    <vc:page-section section="@pageSection"></vc:page-section>
}

The Tag Helper to invoke a view component uses the <vc></vc> element and it added by the addTagHelper directive.

Also, Pascal-cased class and method parameters for Tag Helpers are translated into their lower kebab case - this will be important very soon.

The first View component we'll implement, obviously is the PageSection View component (remember Tag Helpers and the kebab casing convention? 😉)

The path of the Components HTML is ~/Views/Shared/Components/PageSection/Default.cshtml and this is the markup:

@model PageSection
@addTagHelper *, ViewComponentsSample

<h3>@Model.Title</h3>
<vc:section-items section-items="@Model.SectionItems"></vc:section-items>

This component also uses the @addTagHelper directive and it defines a ViewModel of type PageSection which has been a fragment of the IndexViewModel from above.

Besides rendering the Section title it also calls another View component and passes it's own SectionItems (kebab-casing again) to the child View component.

The code behind for these two View components is inside the ~/ViewComponents directory and their code looks like this:

PageSection.cs:

public class PageSection : ViewComponent
{
    public IViewComponentResult Invoke(Models.PageSection section)
    {
        return View("~/Views/Shared/Components/PageSection/Default.cshtml", section);
    }
}

SectionItems.cs:

public class SectionItems : ViewComponent
{
    public IViewComponentResult Invoke(List<Models.SectionItem> sectionItems)
    {
        return View("~/Views/Shared/Components/SectionItems/Default.cshtml", sectionItems);
    }
}

There are some similarities both classes share:

They derive from the ViewComponent base class
They implement the Invoke method which returns a IViewComponentResult
They pass the model to the Views cshtml Template

And now we have some conventions ("magic" 🤙) to understand here to get things working:

The Invoke method is called by thevc TagHelper
The name (and of course the type) of the parameter(s) passed as Tag Helper attributes have to match the name and type of the Invoke method - and kebab casing is your friend again.

You can nest View components at arbitrary levels, so I added another one to finally list the SectionItems.

This is it's template:

@model List<ViewComponentsSample.Models.SectionItem>
@addTagHelper *, ViewComponentsSample
<ul>
    @foreach (var item in Model)
    {
        <vc:section-item text="@item.Text"></vc:section-item>
    }
</ul>

And this is the code behind:

@model string
<li>@Model</li>

Once you get it, it's pretty cool 😎

The sample can be found on GitHub.

Enabling the Kubernetes Dashboard for DigitalOcean Kubernetes

2019-01-03T05:00:00Z

DigitalOcean recently announced the public availability of it's managed Kubernetes offering and it's pretty awesome.

Once you created your cluster following their quickstart, you might want to open the Kubernetes dashboard using kubectl proxy. But browsing http://localhost:8001/api/v1/namespaces/kube-system/services/https:kubernetes-dashboard:/proxy/ will result in a 404 error.

That's because the Kubernetes dashboard is not deployed by default, so let's do this now using:

kubectl create --kubeconfig="your-digitalocean-kubeconfig.yaml" -f https://raw.githubusercontent.com/kubernetes/dashboard/master/aio/deploy/recommended/kubernetes-dashboard.yaml

By the way, if you don't want to always specify the --kubeconfig parameter, you can merge your Cluster configuration into your local Kubernetes Config using this DigitalOcean CLI command (make sure to login first using your DO token) - and I'm assuming this for the next kubectl commands issued in this post:

doctl k8s cluster kubeconfig save <your-do-cluster-name>

Once the configuration is merged, you can list the Kubernetes contexts by issuing this kubectl command

kubectl config get-contexts

Which will output a result similar to this:

CURRENT   NAME                                         CLUSTER                                      AUTHINFO                                           NAMESPACE
          do-fra1-k8s-1-12-1-do-2-fra1-xxxxxxxxxx   do-fra1-k8s-1-12-1-do-2-fra1-xxxxxxxxxx   do-fra1-k8s-1-12-1-do-2-fra1-xxxxxxxxxx-admin
*         docker-for-desktop                           docker-for-desktop-cluster                   docker-for-desktop

As you can see, the current active context is your local Kubernetes and if you want to issue commands against your DigitalOcean Cluster, you'll have to switch the context to this cluster by running

kubectl config use-context do-fra1-k8s-1-12-1-do-2-fra1-xxxxxxxxxx

If everything went fine, you should be able to list the Nodes of your DigitalOcean cluster:

kubectl get nodes

Fingers crossed 🤞, the output should be similar to this (except for the cluster name, of course):

NAME                   STATUS    ROLES     AGE       VERSION
eloquent-hypatia-h12   Ready     <none>    63d       v1.12.1

If you try to access your Kubernetes dashboard now by running kubectl proxy and logging in using your Cluster configuration yaml file, you'll get this error:

Not enough data to create auth info structure.

Read on, we're solving this now 💪!

Next, we need to create a Service Account and a ClusterRoleBinding using this serviceaccount.yaml file:

apiVersion: v1
kind: ServiceAccount
metadata:
  name: <ServiceAccountName> # replace this with the username you want to use
  namespace: kube-system
---
apiVersion: rbac.authorization.k8s.io/v1beta1
kind: ClusterRoleBinding
metadata:
  name: <ServiceAccountName> # replace this with the username you want to use
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: cluster-admin
subjects:
- kind: ServiceAccount
  name: <ServiceAccountName> # replace this with the username you want to use
  namespace: kube-system

Then apply the serviceaccount.yaml using:

kubectl apply -f serviceaccount.yaml

After that, we need to get the access token for the Service Account:

kubectl get secret -n kube-system

This will give you a list like this:

NAME                               TYPE                                  DATA      AGE
csi-do-controller-sa-token-hsgv9   kubernetes.io/service-account-token   3         62d
csi-do-node-sa-token-vz7wk         kubernetes.io/service-account-token   3         62d
default-token-tw59l                kubernetes.io/service-account-token   3         62d
digitalocean                       Opaque                                1         62d
kube-dns-token-7zvjw               kubernetes.io/service-account-token   3         62d
kubernetes-dashboard-certs         Opaque                                0         4m
kubernetes-dashboard-key-holder    Opaque                                2         4m
kubernetes-dashboard-token-fxw8d   kubernetes.io/service-account-token   3         4m
<ServiceAccountName-token-xxxxx>   kubernetes.io/service-account-token   3         17s

Finally display your token:

kubectl describe secret <ServiceAccountName-token-xxxxx> -n kube-system

Name:         <ServiceAccountName-token-xxxxx>
Namespace:    kube-system
Labels:       <none>
Annotations:  kubernetes.io/service-account.name=<ServiceAccountName-token-xxxxx>
              kubernetes.io/service-account.uid=<some-uid>

Type:  kubernetes.io/service-account-token

Data
====
ca.crt:     1156 bytes
namespace:  11 bytes
token:      <here goes your token>

When running kubectl proxy again, now you can enter your token in the login screen here:

If everything went well, you should be able to browse the Kubernetes dashboard now:

Push vs. Pull - regaining control over time

2019-01-08T23:00:00Z

Photo by Patryk Grądys on Unsplash

A few weeks ago I had my tenth Twitter anniversary. But I didn't feel happy about it - quite the opposite.

At that time I was oscillating between leaving Twitter completely one day and following even more people because of their great Tweets the other day.

I started thinking about what I was expecting from Twitter and what was holding me back to get this. To me, the problem was: many people post several Tweets you're deeply interested in and you start following them. But then they're also posting a lot of stuff you're not interested in. Some folks argue that you "buy" the whole person and not just the part you're interested in - but at some amount of people you're following, this won't scale.

So I started an experiment: besides using Lists, I created search definitions using Hashtags and keywords in the Twitter Advanced Search and bookmarked these searches. I also muted a lot of keywords I don't want to read about (this is just distracting noise, let's be honest).

After that a - at that this point in time - crazy idea popped up in my mind: What if I would unfollow everybody? Shouldn't the tweets from the search lead me back to most of the people I followed anyway? Indeed, that's what happened. But now I also read Tweets from many people I had not seen before on Twitter. It's sort of that feeling when you find some awesome stuff on GitHub from people you never heard of.

But I was still unsure.

In the end I did it, because I read this Tweet by the end of 2018:

In 2018, I made a new year's resolution to try and not follow anyone on Twitter for the year. It was the best thing I've done. Make 2019 your year of 0 following, I promise you will not regret it. https://t.co/NTPlQNEbrI
— Carmen Hernández Andoh (@carmatrocity) December 13, 2018

No I was in a rush. I also decided to invest the time saved into reading more Blogs again. So I cleaned up my blog roll and added blogs from people I found using the Twitter Search.

After a while I discovered this pattern: Find people by Search via Hashtags and keywords, subscribe to their blogs and dive deep into topics again - not just bite size fragments and endless discussions on Twitter.

Now that I'm deciding what to search for and when, Twitter has become much less time consuming as there's a plan what to do - and not browsing around just for fun.

Having identified inefficient Twitter usage as a time hog I was thinking about where this was happening outside Twitter and I started questioning using my iPhone for anything else than taking Phone calls - weird.

To cut a long story short - this is my iPhone home screen as of today (as you can see it works for more than ten days already):

My second iPhone screen just contains rarely used stuff or Apps I can't delete anyway.

Besides phone calls, text messages and meeting reminders, there's nothing installed which causes distraction - not even email. If it is really important, people will call anyway - anything else can wait until I'm using a Notebook which is way more efficient for doing work than a small phone screen.

And of course, less push, more pull. You're back in control - not others.

P.S.: Norbert started unfollowing everyone on Twitter today as well, so read his post as well (in german language)

Refresh ASP.NET Core MVC view without reloading the application

2019-12-11T17:00:00Z

After doing no ASP.NET (Core) stuff for while, today I created an ASP.NET Core MVC 3.0 application using dotnet new mvc.

I started the application using dotnet watch run and I was surprised to see the whole application restarting even when I just changed a single character within a MVC View e.g. ./Views/Home/Index.cshtml.

The solution was to add this NuGet package to the project:

Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation

In the Startup.cs I had to change this line:

public void ConfigureServices(IServiceCollection services)
{
     services.AddControllersWithViews();
}

to this

public void ConfigureServices(IServiceCollection services)
{
     services.AddControllersWithViews()
         .AddRazorRuntimeCompilation();
}

Now the application doesn't have to restart for simple HTML/Razor content changes.

Happy coding 😉

Parsing JSON parameters stored in AWS Parameter Store using jq

2020-01-07T17:00:00Z

The other day I had the idea to store some JSON as a AWS Parameter Store value.

If you read the parameter using AWS CLI:

aws ssm get-parameters --name /prod/some-json-param

you get something like this:

{
  "Parameters": [
    {
      "Name": "/prod/some-json-param",
      "Type": "String",
      "Value": "{\n  \"server\": \"\",\n  \"token\": \"\"\n}",
      "Version": 2,
      "LastModifiedDate": 1578353153.788,
      "ARN": "arn:aws:ssm:eu-central-1:1234567890:parameter/prod/some-json-param"
    }
  ],
  "InvalidParameters": []
}

What I wanted to get in a shell script, was the JSON representation of Value like this:

{
  "server": "",
  "token": ""
}

Thanks to the popular jq command, this is quite easy:

aws ssm get-parameters --name /prod/some-json-param | jq '.Parameters | .[] | .Value'

That way, we get the value of Value as a string:

"{\n  \"server\": \"\",\n  \"token\": \"\"\n}"

Another call to jq will give us the desired result:

aws ssm get-parameters --name /prod/some-json-param | jq '.Parameters | .[] | .Value' | jq '.|fromjson'

{
  "server": "",
  "token": ""
}

Happy Coding!

Hot reload tailwindcss changes with browser-sync

2020-09-08T21:00:00Z

The other day I wanted browser-sync to include my changes made to tailwind.config.js or tailwind.css without manually restarting browser-sync after my output.css has been generated.

Initial setup

My initial setup has been tailwindcss and browser-sync installed and configured like this:

- tailwind.css
- tailwind.config.js

The contents of the tailwind.css are based on the default setup:

@tailwind base;

@tailwind components;

@tailwind utilities;

This is the default tailwind.config.js file:

module.exports = {
  purge: [],
  theme: {
    extend: {},
  },
  variants: {},
  plugins: [],
};

The sync script in package.json did look like this:

browser-sync start --server --files \"**/*\

Having this setup, changes to files have been monitored by browser-sync and updated in the browser.

However, changes made to tailwind.css or tailwind.config.js have not been monitored and I had to restart sync after running npx tailwindcss build tailwind.css -o output.css.

Automate all the things

To get rid of this manual step, I installed these devDevependencies:

yarn add -D nodemon npm-run-all postcss-cli

Next, I add the dev, watch-dev and watch scripts, so my scripts section in package.json ends up like this:

{
  "scripts": {
    "sync": "browser-sync start --server --files \"**/*\"",
    "dev": "postcss tailwind.css --output output.css",
    "watch:dev": "nodemon -x npm run dev -w tailwind.config.js -w tailwind.css",
    "watch": "run-p watch:dev sync"
  }
}

Now I can just run yarn watch and browser-sync includes the changes made to tailwind.css and tailwind.config.js instantly.

run-p is the CLI tool installed by npm-run-all and first starts the watch:dev followed by the syncscript. watch-dev runs nodemon which watches the changes made to tailwind.config.js and tailwind.css. If changes are made, postcss is run by the dev script to compile tailwindcss output again.

To make this work, I've added a postcss.config.js:

module.exports = {
  plugins: [require("tailwindcss")("tailwind.config.js")],
};

This step does the work done by tailwindcss build tailwind.css -o output.css before.

That's it 🤷‍♂️

Accessing local domains in local dev environment from Android emulator

2020-09-18T21:00:00Z

Let's consider you're using local domains in development and want access them from Android virtual devices using the Android emulator? Here's how to solve this on macOS using "serverless" pihole.

Given our local IP is 192.168.0.87 and we have defined a domain ui in /etc/hosts.

##
# Host Database
#
# localhost is used to configure the loopback interface
# when the system is booting.  Do not change this entry.
##
192.168.0.87    ui
127.0.0.1       localhost
::1             localhost

If you want to access http://ui from an virtual Android device running in the Android emulator, you get this error in Chrome:

To make it work, we need a DNS server which knows how to resolve http://ui to 192.168.0.87.

An easy way is to run the popular pihole in a Docker container (hence "serverless" in my post title 😉).

Just grab the sample docker-compose.yml from the Docker registry:

version: "3"

# More info at https://github.com/pi-hole/docker-pi-hole/ and https://docs.pi-hole.net/
services:
  pihole:
    container_name: pihole
    image: pihole/pihole:latest
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "67:67/udp"
      - "80:80/tcp"
      - "443:443/tcp"
    environment:
      TZ: 'America/Chicago'
      # WEBPASSWORD: 'set a secure password here or it will be random'
    # Volumes store your data between container upgrades
    volumes:
      - './etc-pihole/:/etc/pihole/'
      - './etc-dnsmasq.d/:/etc/dnsmasq.d/'
    # Recommended but not required (DHCP needs NET_ADMIN)
    #   https://github.com/pi-hole/docker-pi-hole#note-on-capabilities
    cap_add:
      - NET_ADMIN
    restart: unless-stopped

Given http://ui runs on port 80, we need to change the port mapping for port 80 in the docker-compose.yml to another port, e.g. 8080:

ports:
  - "53:53/tcp"
  - "53:53/udp"
  - "67:67/udp"
  - "8080:80/tcp"
  - "443:443/tcp"

Next, we run docker-compose up -d.

Then we can browse to http://localhost:8080/admin.

The Browser should show something like this:

After this, we can click "Login" from the sidebar and login using the password (how to obtain the password is described on the Docker registry page linked above).

Next we can select "Local DNS records" from the sidebar:

Then we add a new DNS entry for ui with IP address 192.168.0.87.

Now it's time to start our emulator again, this time from the command line, as this is the easiest way to pass the DNS server setting:

cd ~/Library/Android/sdk/emulator
emulator -list-avds

Your output will look like this:

Pixel_XL_API_29

Now we can start the emulator again and pass the pihole DNS server running on 192.168.0.87:

./emulator -avd Pixel_XL_API_29 -dns-server 192.168.0.87

Pointing Chrome again to http://ui inside the virtual device should result in something like this now:

To me, local DNS has never been that easy. How about you?

Minimal IAM permissions for AWS CDK deployments

2020-10-01T02:00:00Z

AWS CDK is leveraging AWS CloudFormation to deploy Stacks in AWS.

In addition, AWS CDK may require some data which is being stored in a S3 Bucket named cdktoolkit-stagingbucket-*.

This is the IAM policy IAM assigning to a AWS IAM group which should be able to deploy resources via AWS CDK. Of course, depending on the resources you want to deploy, you need further IAM permissions.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Action": [
                "cloudformation:*"
            ],
            "Resource": "*",
            "Effect": "Allow"
        },
        {
            "Action": "s3:*",
            "Resource": "arn:aws:s3:::cdktoolkit-stagingbucket-*",
            "Effect": "Allow"
        }
    ]
}

The policy gives full access to CloudFormation and all S3 Buckets named cdktoolkit-stagingbucket-*.

Another option is to additionally grant full access for all resources and their actions if the action has been triggered by CloudFormation (or CDK):

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Action": [
                "cloudformation:*"
            ],
            "Resource": "*",
            "Effect": "Allow"
        },
        {
            "Condition": {
                "ForAnyValue:StringEquals": {
                    "aws:CalledVia": [
                        "cloudformation.amazonaws.com"
                    ]
                }
            },
            "Action": "*",
            "Resource": "*",
            "Effect": "Allow"
        },
        {
            "Action": "s3:*",
            "Resource": "arn:aws:s3:::cdktoolkit-stagingbucket-*",
            "Effect": "Allow"
        }
    ]
}

Handle with care...

Update for CDK version 2

Another permission is required for CDK 2:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "sts:AssumeRole"
            ],
            "Resource": [
                "arn:aws:iam::*:role/cdk-*"
            ]
        }
    ]
}

Thanks to James Crowley for pointing this out.

Creating an AWS Cognito user pool with OAuth flows using AWS CDK

2020-10-05T01:00:00Z

I tried to setup an AWS Cognito user pool supporting OAuth 2.0 client credential flow using AWS CDK.

As of version 1.66.0. CDK allows you to create a Cognito User Pool very straight forward:

mkdir idp-stack && cd idp-stack
cdk init idp-stack --language typescript
npm install @aws-cdk/aws-cognito

import { OAuthScope, UserPool } from "@aws-cdk/aws-cognito";

const pool = new UserPool(this, "dev-userpool", {
  userPoolName: "dev-userpool",
});

Next you would assume, you can add a client with client credential flow enabled (as explained in the links above). So here it is:

pool.addClient("console-client", {
  generateSecret: true,
  oAuth: {
    flows: {
      clientCredentials: true,
    },
    scopes: [OAuthScope.custom("https://resource-server//get-todos")],
  },
});

In order to be able to add a custom scope like https://resource-server//get-todos, first you need to create a resource server. But it is not connected to the user pool in terms of a function to call on the pool instance (which makes sense if you think about it for a while).

So here we go:

new CfnUserPoolResourceServer(this, "dev-userpool-resource-server", {
  identifier: "https://resource-server/",
  name: "dev-userpool-resource-server",
  userPoolId: pool.userPoolId,
  scopes: [
    {
      scopeDescription: "Get todo items",
      scopeName: "get-todos",
    },
  ],
});

Now we can use the get-todos scope in our client (take care of the correct convention to specify the scope here):

pool.addClient("console-client", {
  generateSecret: true,
  oAuth: {
    flows: {
      clientCredentials: true,
    },
    scopes: [OAuthScope.custom("https://resource-server//get-todos")],
  },
});

Make sure to take care of the convention for scopes: <resourceserver-identifier>//<scope-name> (notice the double slash).

Additionally we'll specify a domain for our user pool:

pool.addDomain("CognitoDomain", {
  cognitoDomain: {
    domainPrefix: "dev-userpool",
  },
});

Lets try cdk deploy and everything should be fine:

npm run build && npm run cdk deploy

This is the result - and we're done ✅


The stack IdpStack already includes a CDKMetadata resource
IdpStack: deploying...
IdpStack: creating CloudFormation changeset...
[██████████████████████████████████████████████████████████] (6/6)

 ✅  IdpStack

The user pool:

The client:

The resource server:

The full code example can be found here.

Refactoring-safe nested validation with express-validator and ts-simple-nameof

2021-08-10T01:00:00Z

express-validator is a powerful validation and sanitation library.

However, it relies on string property names for the validation to work.

This is not type and refactoring safe, hence error prone.

Let's see if we can fix this...

First, a litte example of how express-validator works (from the official example):

import { body, validationResult } from "express-validator";

const express = require("express");
const app = express();

app.use(express.json());
app.post("/user", (req, res) => {
  User.create({
    username: req.body.username,
    password: req.body.password,
  }).then((user) => res.json(user));
});

app.post(
  "/user",
  // username must be an email
  body("username").isEmail(),
  // password must be at least 5 chars long
  body("password").isLength({ min: 5 }),
  (req, res) => {
    // Finds the validation errors in this request and wraps them in an object with handy functions
    const errors = validationResult(req);
    if (!errors.isEmpty()) {
      return res.status(400).json({ errors: errors.array() });
    }

    User.create({
      username: req.body.username,
      password: req.body.password,
    }).then((user) => res.json(user));
  }
);

As you can see, body('username').isEmail() is using the 'username' string to define a validation rule.

This will become an issue if the username property will be changed - if you don't have tests, your validation will be broken now.

But of course, there's a package for that: ts-simple-nameof:

Parses a class name or a dot-separated property name from a lambda expression and provides some level of type safety using type parameters.

What does this mean exactly?

Here's a simple example:

type Comment = {
  user: {
    posts: Post[];
  };
};

// Returns "posts".
nameof<Comment>((c) => c.user); // returns "user"
// Returns "user.posts".
nameof<Comment>((c) => c.user.posts);

So, ts-simple-nameof returns the name of a property of a TypeScript type, class or interface.

Having ts-simple-nameof at hand, we now can solve our express-validator refactoring issue like this:

type MyCommand = {
  some: {
    nested: {
      property: string;
    };
  };
};

body(nameof<MyCommand>((c) => c.some.nested.property)).exists();

This will ensure, that a arbitrerily deeply nested property can be passed to the body validation function in a refactoring safe way - neat!

A sample repo can be found here. It also shows how you can test express-validator validations.

Writing is thinking - and more

2022-05-30T02:00:00Z

Photo by Yannick Pulver on Unsplash

Recently I came across this tweet:

Writing is not a result of thinking.

Writing is thinking.
— Tiago Forte (@fortelabs) May 29, 2022

This resonates very much with my experience and I want to share it here.

This weekend I did nothing but read and write, with writing predominating. I wrote concepts, ideas and strategies for @klientoapp.

Writing, in my opinion, is even more important when you are a founder on your own. It gives you the opportunity to talk to yourself and reflect on thoughts without having to keep them in your head. This relieves the brain and reduces the cognitive load and avoids multitasking with thoughts.

This, in turn, creates capacity for more thoughts and gets you into flow faster because you can immediately "dump" the brain again with each new thought since you already have all the tools at your disposal (pen and paper or a note-taking app).

When working and developing alone, it's easy to fall into the trap of immediately starting to write code. This leads neither to structured code nor to well thought-out features. You quickly produce a ball of mud and have no clear structure. Indicators are unclear commit messages, no releasable artifacts, and so on.

You work away and never come to a defined end, because without a concept you often overlook and forget important things.

Writing also helps with prioritization. If you write down the features, you know on the one hand the scope and on the other hand you recognize whether this is a USP, commodity or nice to have. You can prioritize accordingly.

When you write, thoughts arise that are not only related to the features. You think more strategically, e.g. also in the direction of investors, hiring etc.

Writing is also helpful when you take a break from a task, e.g. writing code, without losing the context, because you can always pick up the task again when reading what you have written.

I've also gotten into the habit of creating a "TIL" document for each day. This is where notes go in about things I've learned. This can be personal, about the domain or code related on a project. If there are learnings that I can use in other contexts, I store them outside the project and only reference them in the TIL document.

As you may have noticed, I'm Zotero and Zettlr for this.

I am also in the process of using the Zettelkasten method.
I use @zettlr as it also provides a graphic of the "Zettel" (notes).
The recommended book is a great read on this topic. https://t.co/g2wd24x4JT
— Alexander Zeitler (@lxztlr) May 11, 2022

In Zotero I put everything I want to reference, while in Zettlr I write down information in my own words to understand the thought behind it later. I don't make copies of external information in Zettlr - such things are stored in Zotero.

All notes and highlights I make in books and on my kindle I also put in Zotero. That way I avoid having to deal with different media and formats in the long run. Notes and highlights I made in a book or kindle I can delete afterwards, since everything is in Zotero. This also means I'm not dependent on a platform like kindle and when I search I only have to search in one place: for things I've read, listened to or watched it's Zotero, for my own thoughts it's Zettlr. So again, I avoid unnecessary strain on the brain.

Another habit it got into is summarizing inquiries from prospects in my own words after the initial conversation (this can be quite detailed). At the end, I have a list of questions that I can discuss with the prospect and that they can distribute at their company as well. If I receive feedback on the questions, I expand my document. The questions remain, the answers are then also with the questions and so I can reference questions and answers again at the appropriate place. Thus, I have a living documentation of the inquiry process. Of course, this can also be maintained after I got the job...

How do you organize your thoughts and learnings?

Deconstructing a C# record with properties

2022-06-06T22:00:00Z

Photo by Florian Klauer on Unsplash

Today I tried to deconstruct a C# record with properties and I failed.

First, how do you deconstruct a record with positional parameters?

It's as easy like this:

public record Person(
  string FirstName,
  string LastName
);

var janeDoe = new Person("Jane", "Doe");
var (lastName, firstName) = janeDoe;

That's it.

My naïve approach (the record is simplyfied for brevity) to deconstruct a record with properties was like this:

public record Person()
{
  public string Firstname { get; init; }
  public string Lastname { get; init; }
}

Next, I created an instance:

var janeDoe = new Person() { Firstname = "Jane", Lastname = "Doe" };

Now I tried to deconstruct it like I would do with the first sample:

var (lastName, firstName) = janeDoe;

And I got this compiler error:

$ No 'Deconstruct' method with 2 out parameters found for type 'Person'

After reading this error message several times, I got it: the compiler is expecting a method name Deconstruct like this on my Person record type:

public record Person()
{
  public string Firstname { get; init; }
  public string Lastname { get; init; }
  public void Deconstruct(
    out string firstName,
    out string lastName
  ) => (firstName, lastName) = (Firstname, Lastname);
}

Deconstruction now works as expected:

var (lastName, firstName) = janeDoe;

The reason for this issue is quite simple: The C# compiler auto-generates the Deconstruct method when you have a record type with positional parameters but not for record types with properties.

Resizung a Linux (Ubuntu/Xubuntu/Kubuntu) application window exactly

2022-06-20T14:00:00Z

Photo by Adeolu Eletu on Unsplash

Sometimes you need a screenshot of an application window with specific dimensions.

On Linux, you can use the xdotool commandline tool, which is a fake keyboard/mouse input and window management tool for x11.

Using xdotool, resizing a Firefox window to 1024 x 768 pixels is as easy as this command:

xdotool search "Mozilla Firefox" windowsize 1024 768

However, knowing the right window name might fail you, there's a even better solution:

xdotool selectwindow windowsize 1024 768

Now you can just run the command, click a window - and 💥 - the selected window is resized.

⚠️ Note: If you are using Wayland, please be aware this software will not work correctly. ⚠️

Dynamic subdomain per tenant using nginx and Docker

2023-01-11T08:00:00Z

Photo by José Martín Ramírez Carrasco on Unsplash

Even if you don't use B2B SaaS, you might have seen urls like https://theleaddeveloper.slack.com, where you can have your own subdomain on slack.com for your Slack channel.

While playing around with some nginx settings, I noticed that this could actually be used for dynamic subdomains per tenant.

Long story short, here's the solution (which can certainly be optimized):

# sample shows only relevant part of the config, the rest is omitted for the sake of brevity

server {
    listen 443 ssl;

    server_name *.tempuri.org;

     location / { 
        set $tenant ""; 
  
        if ($host ~* "^(.+)\.tempuri.org$") {
          set $tenant $1; 
        }

        resolver 127.0.0.11;
        proxy_pass http://app/tenant?slug=$tenant;
      }   
}

So what's going on there?

Given our domain is tempuri.org, we want tenants to be available via tenantname.tempuri.org, hence our nginx server is listening on *.tempuri.org.

Next we're using a little regular expression to pick up the name of the subdomain (which equals our tenant name/slug) the user entered.

After that we set the DNS resolver to 127.0.0.11 (yes: eleven) which is the internal Docker DNS resolver. That's required to make sure the host name app used for the proxy_pass directive can be resolved. app is the name of the container hosting the actual application which e.g. shows a branded login screen or third party identity providers per tenant.

Serializing .NET objects for use with Alpine.js x-data attribute

2023-01-15T20:00:00Z

Photo by Clint Patterson on Unsplash

Alpine.js allows you set javascript objects in the scope of a HTML tag using the x-data attribute:

<div x-data="{ open: false }">
    <button @click="open = ! open">Toggle Content</button>
     
    <div x-show="open">
        Content...
    </div>
</div>

The data is a plain javascript object whose properties are available to all child elements of the outer div.

Clicking the button will show/hide the content of the inner div.

In a typical SPA like setup you might use fetch together with Alpine's json function to include server side data:

<div
    x-data="{ posts: [] }"
    x-init="posts = await (await fetch('/posts')).json()"
>...</div>

But what to do if you want to render the Razor view and let it include the server side object directly into Alpine's x-data attribute? The closest you can get using out of the box serialization is this:

<div x-data='@Html.Raw(Json.Serialize(new { Open = false}))'></div>

This will render the expected output, and you can toggle the content using the button.

But as you may have noticed, the x-data attribute in the last sample is using single quotes. When using double quotes, the code will break at runtime. Your single quotes might get replaced by double quotes due to IDE settings on when saving the cshtml file.

A better solution would be to use single quotes for the javascript object string and date properties.

One approach could be to replace the instance of IJsonHelper which is being called by Json.Serialize inside the view.

Yet, the implementation is using System.Text.Json which neither allows to use non-quoted property names nor use a different quote char.

So, back to Newtonsoft.Json - here's a possible solution (we could also create a new implementation of IJSonHelper, of course):

public static class JavaScriptConverter
{
  public static IHtmlContent SerializeObject(
    object value
  )
  {
    using var stringWriter = new StringWriter();
    using var jsonWriter = new JsonTextWriter(stringWriter);

    var serializer = new JsonSerializer
    {
      ContractResolver = new CamelCasePropertyNamesContractResolver()
    };

    jsonWriter.QuoteName = false;
    jsonWriter.QuoteChar = '\'';
    serializer.Serialize(jsonWriter, value);

    return new HtmlString(stringWriter.ToString());
  }
}

Using the SerializeObject method, we solve three tasks:

.NET objects get serialized

using camelCase
without quotes in property names, hence creating a Javascript object
using single quotes for string and date properties

Usage inside the view changed to following:

<div x-data="@JavaScriptSerializer.SerializeObject(new { Open = false})"></div>

This is less error-prone but still feels a bit cumbersome.

So let's wrap the JavaScriptSerializer call using a Tag Helper:

[HtmlTargetElement("*", Attributes = "alpine-data")]
public class AlpineTagHelper : TagHelper
{
  public override void Process(
    TagHelperContext context,
    TagHelperOutput output
  )
  {
    output.Attributes.Add("x-data", JavaScriptConverter.SerializeObject(Data));
    base.Process(context, output);
  }

  [HtmlAttributeName("alpine-data")] 
  public object Data { get; set; } = null!;
}

Now lets see how we can use this one.

First, register the Tag Helper in _ViewImports.cshtml:

@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@addTagHelper *, Alpine.TagHelpers

And just use the Tag Helper:

<div alpine-data="new { Open = false }">
  <button x-on:click="open = !open">Show</button>
  <div x-show="open" x-cloak>Some details...</div>
</div>

The rendered result:

<div x-data="{open:false}">
  <button x-on:click="open = !open">Show</button>
  <div x-show="open">Some details...</div>
</div>

The Tag Helper is available as a NuGet package:

dotnet add package Alpine.TagHelpers

A ASP.NET Razor Fragments / Single View approach - not only for HTMX

2023-01-18T10:00:00Z

Photo by Clint Adair on Unsplash

A few months ago, the HTMX team published an essay on so-called template fragments to adhere to the Locality of Behavior (and in my opinion also cohesion) principle in server side rendered views.

If you're using a template engine it is likely you end up with several views like typical parent / child/detail views:

Until now, it has been common that this results in multiple view/component files. However, this comes with a disadvantage:

While separation of concern is improved now, in the same way cohesion and locality of behavior deteriorates:

Locality of Behavior

The behaviour of a unit of code should be as obvious as possible by looking only at that unit of code

Cohesion

Cohesion refers to the degree to which the elements inside a module belong together.

The proposed solution is to have a single template file but being able to address fragments of it by a key. By providing the key by e.g. a controller method calling the view engine, it will just render the fragment.

This is the proposed sample as an HTML file providing template fragment support:

<html>
    <body>
        <div hx-target="this">
          #fragment archive-ui
            #if contact.archived
            <button hx-patch="/contacts/${contact.id}/unarchive">Unarchive</button>
            #else
            <button hx-delete="/contacts/${contact.id}">Archive</button>
            #end
          #end
        </div>
        <h3>Contact</h3>
        <p>${contact.email}</p>
    </body>
</html>

The fragment id here is archive-ui. So you can either render the full view or just two buttons.

When reading this essay after it has been published, it appealed to me a lot, but I didn't think it could be supported by ASP.NET Core Razor without extending the View engine.

So I went over to GitHub and created an issue, requesting for that enhancement. Although it has been triaged and moved to the Backlog this won't be available soon (read: at least not in .NET 8).

After creating the issue, I was repeatedly annoyed by the lack of support, but did not pursue the issue further - until yesterday.

The topic came up again in the dotnet-htmx channel on the HTMX discord server.

Based on the discussion, a rough idea formed in my head how this could be solved without extending Razor at all, getting full IDE support and all the like.

Here's what I came up with - let's just talk code:

First, we define some models:

public class FragmentModel
{
  public FragmentModel(
    string fragmentId
  )
  {
    FragmentId = fragmentId;
  }

  public string FragmentId { get; set; }
}

public class ChildModel : FragmentModel
{
  public int Id { get; }

  public ChildModel(
    int id
  ) : base("Detail")
  {
    Id = id;
  }
}

public class ParentModel : FragmentModel
{
  public List<ChildModel> Childs { get; }

  public ParentModel(
    List<ChildModel> childs
  ) : base("Full")
  {
    Childs = childs;
  }
}

Then we define a single View file:

@model RazorFragments.Models.FragmentModel

@{
  Layout = "_Layout";
}


@{
  void RenderDetail(
    ChildModel child)
  {
    <div class="bg-gray-200">
      @Html.ActionLink(child.Id.ToString(), "Detail", new
      {
        id = child.Id
      })
    </div>
  }

  void RenderFull(
    ParentModel parent)
  {
    <div class="bg-blue-500 p-4">
      @{
        @foreach (var parentChild in parent.Childs)
        {
          RenderDetail(parentChild);
        }
      }
    </div>
  }
}


@{
  switch (Model.FragmentId)
  {
    case "Full":
      RenderFull(Model as ParentModel);
      break;
    case "Detail":
      RenderDetail(Model as ChildModel);
      break;
  }
}

And everything gets tied together in our controller:

public class RazorFragmentController : Controller
{
  // GET
  public IActionResult Index()
  {
    return View(
      new ParentModel(
        new List<ChildModel>()
        {
          new(1),
          new(2)
        }
      )
    );
  }

  [Route("/detail/{id}")]
  public IActionResult Detail(
    [FromRoute] int id
  )
  {
    return View("Index", new ChildModel(id));
  }
}

This is just a first draft stitched together in the middle of the night so I'm curious about your thoughts, feedback and suggestions for improvement.

The full sample can be found on GitHub.

Update (2023/01/26)

I created another sample which is closer to the mockup in from the intro:

List view

Details view

ASP.NET Razor Pages Fragments / Single View approach

2023-01-27T20:00:00Z

Photo by Olga Deeva on Unsplash

I got some feedback for my previous post: Will the single view approach work with ASP.NET Razor Pages instead of MVC Views and Controllers?

Well, I'm a total Razor Pages noob, but this didn't stop me to give it a try.

Long story short: it works, but I might be doing it totally wrong.

Here's the source:

Biggest issue upfront: how do we get multiple GET handlers in our Page Model?

Jerrie Pelser has a post that solved it for me.

Our Page now has this route template:

@page "{handler?}"

This makes stuff dynamic, and we can end up having multiple GET requests within the same Code for the page.

Thus, our page looks very similar to our MVC View except for the Model which is now a child property if the Page Model:

@page "{handler?}"
@model IndexModel
@{
ViewData["Title"] = "Home page";
}

@{
    void RenderDetail(ChildModel child)
    {
        <div class="bg-gray-200">
            <a href="@Url.PageLink("Index", "Details", new {Id = child.Id})">@child.Id</a>
        </div>
    }

    void RenderFull(ParentModel parent)
    {
    <div class="bg-blue-500 p-4">
        @{
        @foreach (var parentChild in parent.Childs)
        {
        RenderDetail(parentChild);
        }
        }
    </div>
    }
}


@{
    switch (Model.PageModel.FragmentId)
    {
        case "Full":
            RenderFull(Model.PageModel as ParentModel);
            break;
        case "Detail":
            RenderDetail(Model.PageModel as ChildModel);
            break;
        default:
            throw new ArgumentOutOfRangeException();
    }
}

The page model looks like this:

using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;

namespace RazorPagesFragments.Pages;

public class IndexModel : PageModel
{
  private readonly ILogger<IndexModel> _logger;
  public FragmentModel PageModel { get; set; } = null!;

  public IndexModel(
    ILogger<IndexModel> logger
  )
  {
    _logger = logger;
  }

  public void OnGet()
  {
    PageModel = new ParentModel(
      new List<ChildModel>()
      {
        new(1),
        new(2)
      }
    );
  }

  public void OnGetDetails(
    [FromQuery] int id
  )
  {
    PageModel = new ChildModel(id);
  }
}

public class FragmentModel
{
  public FragmentModel(
    string fragmentId
  )
  {
    FragmentId = fragmentId;
  }

  public string FragmentId { get; set; }
}

public class ChildModel : FragmentModel
{
  public int Id { get; }

  public ChildModel(
    int id
  ) : base("Detail")
  {
    Id = id;
  }
}

public class ParentModel : FragmentModel
{
  public List<ChildModel> Childs { get; }

  public ParentModel(
    List<ChildModel> childs
  ) : base("Full")
  {
    Childs = childs;
  }
}

And that's it.

If I have missed something due to my lack of Razor Pages knowledge, feel fry to drop me a line how to improve it.

The full sample can be found on GitHub.

Fixing my .NET 6 SDK installation after installing .NET SDK 7.0 on Xubuntu

2023-01-27T20:00:00Z

Artwork by Ashley Willis on GitHub

I'm running on Xubuntu 22.04 day in day out working with .NET most of the time, so downtime is not an option.

.NET 6 SDK was installed using the dotnet6 package from Ubuntu.

Shortly after Microsoft released .NET 7, I wanted to upgrade, but it did not work because of this error:

Package 'dotnet-sdk-7.0' has no installation candidate

So, no .NET 7 for me so far.

Last weekend has been the time when I finally wanted to install .NET 7 SDK side-by-side with the existing .NET 7 SDK because I wanted to test out some stuff:

This 👇https://t.co/WdanSAlhvW

And side projects ofc https://t.co/xrrLC8tV35 pic.twitter.com/rzMkeyIHYR
— Alexander Zeitler (@lxztlr) January 27, 2023

As I knew there would be some trouble I pulled out the Microsoft installation Guide for .NET 7 on Ubuntu. I also had an eye on the troubleshooting guide for mixed installations like my scenario was.

So my first attempt has been this:

wget https://packages.microsoft.com/config/ubuntu/22.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
rm packages-microsoft-prod.deb

And it failed (obviously, because this would not be worth a blog post):

Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
Package dotnet-sdk-7.0 is not available, but is referred to by another package.
This may mean that the package is missing, has been obsoleted, or
is only available from another source

E: Package 'dotnet-sdk-7.0' has no installation candidate

Back to the troubleshooting guide, I prioritized the Microsoft package feed for the dotnet-sdk-7.0 package as described in the guide by editing / adding /etc/apt/preferences:

Package: dotnet-sdk-7.0
Pin: origin "packages.microsoft.com"
Pin-Priority: 999

Next sudo apt update && sudo apt install dotnet-sdk-7.0: no errors.

Let's try dotnet --list-sdks:

6.0.405 [/usr/share/dotnet/sdk]
7.0.102 [/usr/share/dotnet/sdk]

Restrained joy. Should that have been it?

Of course - not.

Back to my major project, I noticed that .NET 6 SDK (via dotnet run --framework net6.0) stopped working:

dotnet run --framework net6.0   
Building...
You must install or update .NET to run this application.

App: /home/alexzeitler/src/myproject/bin/Debug/net6.0/myproject
Architecture: x64
Framework: 'Microsoft.NETCore.App', version '6.0.0' (x64)
.NET location: /usr/share/dotnet

The following frameworks were found:
  7.0.2 at [/usr/share/dotnet/shared/Microsoft.NETCore.App]

Learn about framework resolution:
https://aka.ms/dotnet/app-launch-failed

To install missing framework, download:
https://aka.ms/dotnet-core-applaunch?framework=Microsoft.NETCore.App&framework_version=6.0.0&arch=x64&rid=ubuntu.22.04-x64

Maybe add a global.json inside project folder?

{
  "sdk": {
    "version": "6.0.405",
    "rollForward": "latestMinor",
    "allowPrerelease": false
  }
}

Nobody likes your global.json, Alex.

"Maybe I should just move on and work with .NET 7 locally...".

Didn't want that, but I didn't want to invest more time and I also wanted to keep .NET 7 SDK installed.

So, I updated the csproj file like this to target .NET 6 and .NET 7:

<TargetFrameworks>net6.0;net7.0</TargetFrameworks>

Now I could use build and run my project locally using .NET 7 and tests did also work.

That's all nice but how about some broken CI builds?

Of course this didn't work as expected because the project has multiple targets now, and you need to specify a framework version in your Docker build.

"Well, that's easy".

No, it's not.

dotnet restore doesn't understand --framework flag.

But: it does understand a MSBuild parameter called TargetFramework.

FROM mcr.microsoft.com/dotnet/sdk:6.0 AS build-env
WORKDIR /app

# Copy everything
COPY . ./
# Restore as distinct layers
RUN dotnet restore -p:TargetFramework=net6.0

So, this should also work for dotnet publish one might guess...

FROM mcr.microsoft.com/dotnet/sdk:6.0 AS build-env
WORKDIR /app

# Copy everything
COPY . ./
# Restore as distinct layers
RUN dotnet restore -p:TargetFramework=net6.0
# Build and publish a release
RUN dotnet publish --framework net6.0 -p:TargetFramework=net6.0 -c Release -o out 

# Build runtime image
FROM mcr.microsoft.com/dotnet/aspnet:6.0
WORKDIR /app
COPY --from=build-env /app/out .
ENTRYPOINT ["dotnet", "MyApp.dll"]

Hard "no", again.

And it's not interested in your --framework flag also, Alex.

For whatever reason, this command did work outside the Docker build.

Meanwhile, I got a suggestion to try the .NET Core plugin for the asdf version manager and do a manual install (did I mention we really should have something like nvm for Node?).

I was tempted to walk this path, but something dragged me to take a look at the issues for the plugin first.

And there it was: Rider can't detect dotnet sdk.

And this ongoing issue dug another rabbit hole.

Ok, time to chop some wood.

It's been late in the evening and I did not want to start the next day with a broken installation, so I decided to wipe .NET SDK completely and start with a fresh install.

sudo apt remove dotnet-sdk-6.0 dotnet-sdk-7.0

Now dotnet --version shouldn't work, but...

6.0.13

Wait, what?

Turns out, there's still something left from the Ubuntu .NET 6 SDK install. So comment out the settings in /etc/apt/preferences.

sudo apt remove dotnet6

Finally, gone.

Next: reinstall .NET 6 SDK.

Undo the comment out of the settings in /etc/apt/preferences:

Package: dotnet-* aspnetcore-* netstandard-*
Pin: origin "packages.microsoft.com"
Pin-Priority: 999

sudo apt clean
sudo apt update
sudo apt install dotnet-sdk-6.0

No errors.

dotnet --version
A fatal error occurred. The folder [/usr/share/dotnet/host/fxr] does not exist

Great.

But apt install did tell me, the dependencies for dotnet-sdk-6.0 have been installed...

Turns out, they have been installed from Ubuntu packages and dotnet-sdk-6.0 has been installed from Microsoft packages.

So, remove everything again, but also the dependencies:

sudo apt remove dotnet-sdk-6.0
sudo apt autoremove #this will remove the unused dependencies

Update the /etc/apt/preferences again. This time include all dependencies:

Package: dotnet-* aspnetcore-* netstandard-*
Pin: origin "packages.microsoft.com"
Pin-Priority: 999

Next try:

sudo apt update
sudo apt install dotnet-sdk-6.0

dotnet --version
6.0.405

Good. Next: Run the app:

dotnet run

[08:32:51 INF] Now listening on: https://0.0.0.0:5001
[08:32:51 INF] Now listening on: http://0.0.0.0:5000
[08:32:51 DBG] Loaded hosting startup assembly MyProject
[08:32:51 DBG] Loaded hosting startup assembly Microsoft.AspNetCore.Watch.BrowserRefresh
[08:32:51 INF] Application started. Press Ctrl+C to shut down.
[08:32:51 INF] Hosting environment: Development
[08:32:51 DBG] Hosting started

Ok, let's try dotnet watch run.

dotnet watch run
You must install .NET to run this application.

App: /home/alexzeitler/.dotnet/tools/dotnet-outdated
Architecture: x64
App host version: 6.0.13
.NET location: Not found

Learn about runtime installation:
https://aka.ms/dotnet/app-launch-failed

Download the .NET runtime:
https://aka.ms/dotnet-core-applaunch?missing_runtime=true&arch=x64&rid=ubuntu.22.04-x64&apphost_version=6.0.13

Still something broken - but what?

Looks like it's not just me having issues: .NET runtime not found on Ubuntu

Ok, let's follow the advice and set /etc/dotnet/install_location to /usr/share/dotnet.

Then fix the missing DOTNET_ROOT environment variable and add (re-add?) that path to the PATH environment variable in ~/.zshrc:

export DOTNET_ROOT=/usr/share/dotnet
export PATH=$PATH:$DOTNET_ROOT

Source the updated .zshrc:

. ~/.zshrc

Try a dotnet tool:

dotnet-outdated
Discovering projects...The directory '/home/alex' does not contain any solutions or projects.

Fine. Try to dotnet watch run the project again:

[08:32:51 INF] Now listening on: https://0.0.0.0:5001
[08:32:51 INF] Now listening on: http://0.0.0.0:5000
[08:32:51 DBG] Loaded hosting startup assembly MyProject
[08:32:51 DBG] Loaded hosting startup assembly Microsoft.AspNetCore.Watch.BrowserRefresh
[08:32:51 INF] Application started. Press Ctrl+C to shut down.
[08:32:51 INF] Hosting environment: Development
[08:32:51 DBG] Hosting started

Ok. I can get my work done tomorrow.

But what about .NET 7 SDK?

"It's just 1:30am so why not give it a try again?"

sudo apt update
sudo apt install dotnet-sdk-7.0

No errors.

dotnet --list-sdks
6.0.405 [/usr/share/dotnet/sdk]
7.0.102 [/usr/share/dotnet/sdk]

Open the .NET 6 Project in Rider with only .NET 6 targeted again:

<TargetFramework>net6.0</TargetFramework>

Loads.

Try to build.

Works.

Try to run the tests.

Works.

Open a .NET 7 project.

Try to build.

Works.

Try to run the tests.

Works.

YES!

ASP.NET: The default developer certificate could not be found

2023-03-04T14:00:00Z

Photo by Georg Bommeli on Unsplash

After playing around with ASP.NET developer certificates on macOS I couldn't get it back to work. Whenever the app started, I got this exception on startup:

Unable to configure HTTPS endpoint. No server certificate was specified, and the default developer certificate could not be found or is out of date.

Whatever I tried (dotnet dev-certs https [ --clean / --trust ]), I couldn't get it to work.

I also removed the certs manually from macOS Keychain.

After a while I noticed, that in ~/.aspnet/dev-certs/https even after a dotnet dev-certs https --clean there has still been one .pfx left, owned by root.

After deleting this one, ASP.NET picked up a fresh generated developer certifcate correctly again.

Quickly navigate between Finder folders using the keyboard on macOS

2023-03-05T08:00:00Z

Photo by Glenn Carstens-Peters on Unsplash

Recently I learned how to navigate to a folder quickly when opening or saving files on macOS using ⇧ + ⌘ + G on the keyboard.

This shortcut also works when having folders open in Finder:

ASP.NET Core developer certificate: ERR_SSL_VERSION_OR_CIPHER_MISMATCH on macOS

2023-03-08T21:00:00Z

Photo by Kenny Eliason on Unsplash

I've been facing an issue with the ASP.NET developer certificates for ASP.NET Core 7 apps using HTTPS on macOS:

ERR_SSL_VERSION_OR_CIPHER_MISMATCH

Whatever I tried (dotnet dev-certs https [ --clean / --trust ]), I couldn't get it to work.

I also removed the certs manually from macOS Keychain.

Then I found this issue on GitHub which suggested adding this PropertyGroup to the csproj file:

<PropertyGroup>
  <UseAppHost>false</UseAppHost>
</PropertyGroup>

In fact it fixed the error.

Now I could use some help from you: Why does this setting fix it?

Can't delete a note in PDF using Preview on macOS

2023-03-11T19:00:00Z

While reviewing some PDF articles I took notes that I wanted to delete later on using macOS Preview app. But it didn't work as expected.

Here's the crime scene:

The most obvious things to try are hitting the backspace key (also together with ⇧ and/or ⌘). But this didn't work.

Lucky me, there's a workaround.

Open the "Inspector" using ⌘ + i shortcut:

There you can select a note and once it's highlighted, it can be removed using the backspace key:

Late 2025 Update

Since this is one of the most read posts on my blog, I would like to point out that I completely stopped using macOS since shortly after the post in 2023.

Linux has been my daily driver since 2014 and everything I've still been using macOS for, I can do on Linux since then.

Recently I've been switching from Ubuntu to Omarchy, which is the most enjoyable OS I've ever used.

IdentityGeneratorTemplateMode2 does not contain a definition for "UseSQLite"

2023-03-18T09:00:00Z

The other day I tried to scaffold ASP.NET Identity for Sqlite (actually I wanted to scaffold it for Postgres but that's another story) from the CLI:

dotnet aspnet-codegenerator identity -dc IdentityDbContext -u AppUser -f -gl -dbProvider sqlite

Straight forward, but I got this error:

IdentityGeneratorTemplateMode2 does not contain a definition for 'UseSQLite'.

The project I was trying to add Identity to, has been a spike where I was trying out some stuff using Alba.

One thing I had changed in the project compared to others where I was scaffolding Identity successfully, was that the project contained a Startup.cs file.

As I was stuck I just tried guessing and deleted the Startup.cs file and ran the scaffolding again.

And boom 💥, it did work successfully again.

Right now I don't know why the file caused this issue but I provided my learning to an existing GitHub issue so Microsoft can figure it out.

Update

Make sure to read the follow up.

Twitter preview Photo by Jackson Simmer on Unsplash

Entity Framework Core: Why you should never name your DbContext 'IdentityDbContext'

2023-03-18T17:00:00Z

This is more or less a follow up to the previous post.

As said in the post already, I was playing around with Startup.cs style of application start up together with Entity Framework Core / ASP.NET Identity scaffolding.

So after I got Identity scaffolded, I re-added the Startup.cs and wanted to move on with migrations.

My Program.cs looked like this:

public class Program
{
  public static void Main(
    string[] args
  )
  {
    CreateHostBuilder(args)
      .Build()
      .Run();
  }

  public static IHostBuilder CreateHostBuilder(
    string[] args
  ) =>
    Host.CreateDefaultBuilder(args)
      .ConfigureWebHostDefaults(webBuilder => { webBuilder.UseStartup<Startup>(); });
}

This was the Startup.cs:

public class Startup
{
  public IConfiguration Configuration { get; }

  public Startup(
    IHostEnvironment env
  )
  {
    var builder = new ConfigurationBuilder()
      .SetBasePath(env.ContentRootPath)
      .AddJsonFile(
        "appsettings.json",
        optional: false,
        reloadOnChange: true
      )
      .AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true)
      .AddEnvironmentVariables();
    Configuration = builder.Build();
  }


  // This method gets called by the runtime. Use this method to add services to the container
  public void ConfigureServices(
    IServiceCollection services
  )
  {
    var connectionString = Configuration.GetConnectionString("IdentityDbContextConnection") ??
                           throw new InvalidOperationException(
                             "Connection string 'IdentityDbContextConnection' not found."
                           );

    services.AddDbContext<IdentityDbContext>(options => options.UseNpgsql(connectionString));

    services.AddDefaultIdentity<AppUser>(options => options.SignIn.RequireConfirmedAccount = true)
      .AddEntityFrameworkStores<IdentityDbContext>();

    services.AddControllersWithViews();
  }

  // This method gets called by the runtime. Use this method to configure the HTTP request pipeline
  public void Configure(
    IApplicationBuilder app,
    IWebHostEnvironment env
  )
  {
    // Configure the HTTP request pipeline.
    if (!env.IsDevelopment())
    {
      app.UseExceptionHandler("/Home/Error");
      // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
      app.UseHsts();
    }

    app.UseHttpsRedirection();
    app.UseStaticFiles();

    app.UseRouting();

    app.UseAuthorization();

    app.UseEndpoints(
      endpoints =>
      {
        endpoints.MapControllerRoute(
          name: "default",
          pattern: "{controller=Home}/{action=Index}/{id?}"
        );
      }
    );
  }
}

The next step would be to create the first migration and seed the database:

dotnet ef migrations add CreateIdentitySchema

Straight forward, one might think... but no:

More than one DbContext was found. Specify which one to use. Use the '-Context' parameter for PowerShell commands and the '--context' parameter for dotnet commands.

So, let's get a list of the contexts available using dotnet ef dbcontext list:

dotnet ef dbcontext list
Build started...
Build succeeded.
Microsoft.AspNetCore.Identity.EntityFrameworkCore.IdentityDbContext
WebAppWithIdentity.Areas.Identity.Data.IdentityDbContext

Ok, let's try to use a full qualified name then:

dotnet ef database update --context WebAppWithIdentity.Areas.Identity.Data.IdentityDbContext

Build started... Build succeeded. Unable to create an object of type 'IdentityDbContext'. For the different patterns supported at design time, see https://go.microsoft.com/fwlink/?linkid=851728

That's not funny, tbh.

Well, let's go back to scaffolding and try this one (still with Startup.cs in use):

dotnet aspnet-codegenerator identity -dc SecurityDbContext -u AppUser -f -gl -dbProvider sqlite

Result:

Building project ...
Finding the generator 'identity'...
Running the generator 'identity'...
RunTime 00:00:17.25

Umm... no let's list the contexts again:

dotnet ef dbcontext list
Build started...
Build succeeded.
WebAppWithIdentity.Areas.Identity.Data.SecurityDbContext

Well, that's interesting.

Now, let's try to run the migrations:

dotnet ef migrations add CreateIdentitySchema
Build started...
Build succeeded.
Done. To undo this action, use 'ef migrations remove'

Wow!

And the final step: apply the changes to the actual database:

dotnet ef database update

Build started...
Build succeeded.

# shortened the output a bit here
info: Microsoft.EntityFrameworkCore.Database.Command[20101]
      Executed DbCommand (14ms) [Parameters=[], CommandType='Text', CommandTimeout='20']
      CREATE UNIQUE INDEX "UserNameIndex" ON "AspNetUsers" ("NormalizedUserName");
info: Microsoft.EntityFrameworkCore.Database.Command[20101]
      Executed DbCommand (14ms) [Parameters=[], CommandType='Text', CommandTimeout='20']
      INSERT INTO "__EFMigrationsHistory" ("MigrationId", "ProductVersion")
      VALUES ('20230318144833_CreateIdentitySchema', '7.0.4');
Done.

Ok, lessons learned:

Never name your DbContent IdentityDbContext

Integration testing an ASP.NET Core 7 app with ASP.NET Identity using Alba

2023-03-20T22:00:00Z

Photo by Jeswin Thomas on Unsplash

As you might have noticed on Twitter that I started to evaluate Wolverine (formerly known as "JasperFx") to become the Message Bus for my SaaS apps (e.g. kliento).

One of the benefits of Wolverine: it's part of the "Critter Stack for .NET".

If you want to understand what that means, I recommend this blog post by Jeremy D. Miller.

Another thing you might know about me (from here, here or here), is that I'm using HTMX instead of SPA libraries like React.

This leads to the fact I'm using ASP.NET Identity for user management.

Now I wanted to refactor an ASP.NET Core 7 app with ASP.NET Identity to use Wolverine and being integration tested using Alba.

In a first step, I started to refactor my tests to Alba, so I could integration test async operations as described in the post by Jeremy and be prepared for a second refactoring to Wolverine.

And that's where things got interesting (read: went south).

The easiest way to get a test set up using Alba is possibly this:

[Fact]
public async Task should_say_hello_world()
{
    // Alba will automatically manage the lifetime of the underlying host
    await using var host = await AlbaHost.For<global::Program>();
    
    // This runs an HTTP request and makes an assertion
    // about the expected content of the response
    await host.Scenario(_ =>
    {
        _.Get.Url("/");
        _.ContentShouldBe("Hello World!");
        _.StatusCodeShouldBeOk();
    });
}

That way the application under test will be bootstrapped in the exact same way like your production app.

Now you might want to run some tests in parallel using different databases (as you might have guessed, I'm using Marten) with dynamic connection strings being generated during test setup (note to self: this could be another blog post).

This means you need to have the same middleware pipeline etc. but with different parameters.

This all works pretty nice using Marten and other stuff but when it came to modifying the configuration for ASP.NET Identity at runtime or to add it with different configuration settings errors like these happened:

InvalidOperationException: Scheme already exists: Identity.Application Microsoft.AspNetCore.Authentication.AuthenticationOptions.AddScheme(string name, Action configureBuilder)...

So, I was in need of a different way to bootstrap my application under test - and in the end, the whole application (confirming my opinion that real world applications won't use the minimal APIs bootstrapping approach 🫢).

Lucky me, the Alba "Getting started" guide mentioned this blog post by Andrew Lock, in which he describes the evolution of ASP.NET Core application bootstrapping since the beginning of ASP.NET Core (if you follow all linked posts - you better grab some coffee before you start reading).

The solution I came up with is this - we'll start with a test asserting that a redirect to the login page happens when trying to access the application as an anonymous user:

public class When_calling_app_as_anonymous_user : IAsyncLifetime
{
  private AlbaHost? _host;

  public async Task InitializeAsync()
  {
    var testServices = new TestServices();
    var testConfiguration = await testServices.GetTestConfigurationRoot();
    var hostBuilder = ConfigureHost.GetHostBuilder(testConfiguration);
    _host = new AlbaHost(hostBuilder);

    await _host.MigrateIdentityDatabase();
  }

  [Fact]
  public async Task should_redirect_to_login()
  {
    await _host?.Scenario(
      _ =>
      {
        _.Get.Url("/");
        _.Header("Location")
          .ShouldHaveValues("http://localhost/Identity/Account/Login?ReturnUrl=%2F");
        _.StatusCodeShouldBe(302);
      }
    );
  }

  public async Task DisposeAsync() => await _host.DisposeAsync();
}

TestServices does a ton of stuff like handling the database bootstrapping/seeding mentioned above (yes, this really requires a blog post on it's own).

GetTestConfigurationRoot(), as it's name suggests builds an in-memory configuration for things like databases, including the ASP.NET Identity database (each test has it's own test event store and identity database).

The key thing for this post however is ConfigureHost.GetHostBuilder(testConfiguration) which returns an IHostBuilder instance which Alba is happily using to create an IAlbaHost instance from:

public static class ConfigureHost
{
  public static IHostBuilder GetHostBuilder(
    IConfigurationRoot configuration
  )
  {
    var hostBuilder = Host.CreateDefaultBuilder();

    hostBuilder.AddLogging();
    new SerilogLoggerFactory(Log.Logger)
      .CreateLogger<Program>();
    
    hostBuilder.ConfigureWebHostDefaults(
      builder =>
      {
        builder.ConfigureServices(collection => collection.ConfigureAppServices(configuration));
        builder.UseConfiguration(configuration);
        builder.Configure(
          (
            context,
            app
          ) =>
          {
            if (!context.HostingEnvironment.IsDevelopment())
            {
              app.UseExceptionHandler("/Error");
              app.UseHsts();
            }

            app.UseStaticFiles();

            app.UseRouting();

            app.UseAuthentication();
            app.UseAuthorization();

            app.UseEndpoints(
              endpoints =>
              {
                endpoints.MapControllers();
                endpoints.MapRazorPages();
                endpoints.MapDefaultControllerRoute()
                  .RequireAuthorization();
              }
            );
          }
        );
      }
    );

    return hostBuilder;
  }
}

This creates an ASP.NET Host with MVC, Controllers and Identity set up.

The magic happens in collection.ConfigureAppServices(configuration)) - I removed the event store and other configuration stuff for brevity:

public static class ConfigureServices
{
  public static IServiceCollection ConfigureAppServices(
    this IServiceCollection services,
    IConfigurationRoot configuration
  )
  {
    var identityTestConnectionString = configuration.GetConnectionString("Identity");
    services.AddDbContext<IdentityDbContext>(
      options =>
        options.UseNpgsql(identityTestConnectionString)
    );

    services.AddDefaultIdentity<AppUser>(options => options.SignIn.RequireConfirmedAccount = false)
      .AddEntityFrameworkStores<IdentityDbContext>();

    services.AddControllersWithViews()
      .AddRazorRuntimeCompilation();
    services.Configure<RazorViewEngineOptions>(
      o => o.ViewLocationExpanders.Add(new FeatureFolderLocationExpander())
    );
    services.AddMvc();

    return services;
  }
}

That way I can spin up concurrent async integration tests (the async part has to be validated when Wolverine is added to the game).

What's left is the application itself to be bootstrapped in the exact same way but with different configuration:

var configuration = new ConfigurationBuilder()
  .AddEnvironmentVariables()
  .AddCommandLine(args)
  .AddJsonFile("appsettings.json")
  .AddJsonFile($"appsettings.{Environment.GetEnvironmentVariable("ASPNETCORE_ENVIRONMENT")}.json", optional: true)
  .Build();

var builder = ConfigureHost.GetHostBuilder(configuration);
builder
  .Build()
  .Run();

Well, that's it and works fine so far.

Maybe there's an easier / better solution - if so, please let me know!

I'm printing out websites - you might want to do it, too

2023-04-01T20:00:00Z

Photo by Mufid Majnun on Unsplash

I'm printing out websites on purpose.

This may sound like an April Fool's joke, but I'm serious.

But I don't print them on paper, I print them as PDF files for the following reasons:

I'm using Logseq as a "second brain".

Logseq comes with a ton of useful features and one of them are PDF annotations.

Here's the official video demoing the feature:

Logseq to me by far is the most comfortable way to annotate websites across multiple computers and integrate them with my existing knowledge graph - if you print them to PDF and import them to Logseq.

Another win of this method: I won't loose the information if the website with the post goes dark at some point in time...

The workflow

Open an arbitrary blog post or article you want to annotate:

Next, I'm activating Firefox Reader mode:

Then, I'm calling the Print dialog and disable printing headers and footers:

And finally, I can just drag and drop the PDF file into my Logseq page created for this post and start highlighting and annotating.

How do you annotate and highlight websites?

Exporting and importing Live Templates in JetBrains Rider

2023-04-02T22:00:00Z

I love JetBrains Rider and I'm using it on every Platform: Xubuntu, macOS and Windows. That's great a great experience but sharing Live Templates between the platforms is a bit tricky.

Things might be easier if you're using JetBrains sync but I'm using the repository sync for ages now....

The obvious option might be to use the "Save" button in the "Live Template" settings. However, if this would work, I wouldn't write this post.

The aforementioned option only export none .NET live templates.

So how do we do it for C# (and F# I guess)?

Exporting

First, open the "Manage Layers" dialog - I'm doing this via the Actions Panel (double shift keyboard shortcut). Then right click "This computer" (or where ever you want to export the live templates from) and select "Export to File...":

Then tick the checkbox "Live Templates":

Next, assign a file name and you're done with exporting.

Importing

Bring up the "Manage Layers" dialog again and select "Import from" ➡️ "Import from File..."

Select a file containing exported Live Templates:

Tick the "LiveTemplates" checkbox

And we're done 💥️

Just double check the templates have been imported:

Inspecting ASP.NET integration testing logs made easy with JetBrains Rider

2023-04-05T21:00:00Z

Photo by Nathan Bingle on Unsplash

The other day I was integration testing a Saga in the kliento code base. The tests failed and I wanted to skim through the logs to find something meaningful.

Scrolling through thousands of lines of log in a monochrome style is no fun... (to me this approach sometimes is easier than debugging anyway).

First things first: how do I get this output?

When spinning up my tests in Alba, I'm registering a XUnit sink for Serilog, so I get my logs redirected to the test output window in Rider:

public class When_recording_a_lead_inquiry_from_email : IAsyncLifetime
{
  public When_recording_a_lead_inquiry_from_email(
    ITestOutputHelper testOutputHelper
  )
  {
    _testOutputHelper = testOutputHelper;
  }

  public async Task InitializeAsync()
  {
    var testServices = new TestServices();
    var configuration = await testServices.GetTestConfigurationRoot();

    var serilogLogger = Log.Logger = new LoggerConfiguration()
      .MinimumLevel.Debug()
      .WriteTo.Console()
      .WriteTo.TestOutput(_testOutputHelper)
      .CreateLogger();

    var dotnetILogger = new SerilogLoggerFactory(serilogLogger)
      .CreateLogger<Program>();

    var builder = ConfigureHost.GetHostBuilder(
      configuration,
      services =>
      {
        services.AddSingleton<ILogger>(dotnetILogger);
      });

    // arrange act assert...
  }
}

My test output looks like this then:

While scrolling through the look I was thinking "would be nice if there would be some color coding for the log in Rider...".

And the next step was to spin up a search which eventually ended up on the landing page for "GrepConsole", a plugin for IntelliJ based IDEs like Rider which does exactly what I was looking for: colorize my test output logs.

After playing around with some settings, my logs now look like this:

Much easier to spot exceptions, isn't it?

What's even better: you can add arbitrary expressions to filter and colorize fragments or lines.

So I set up a section for regular .NET log output colors and I added another one for Wolverine status messages. That way I can easily spot successful or failed messages.

That's my GrepConsole config so far:

Right now, there's only one downside: I didn't find a way in Rider to export/import these settings although this seems to work in other JetBrains IDEs.

Update

Looks like the settings get synced using repository sync 🎉️

How to stop JetBrains Rider asking to add files to Git version control

2023-04-07T21:00:00Z

Photo by Dim Hou on Unsplash

Whenever I've created a new project in Rider and added some files to the project, Rider was asking to add these file to Git / Version control:

Ticking "Don't ask again" only helps for this project, but of course there must be a global setting.

Indeed, a setting can be found in File | Settings | Version Control | Confirmation:

So let's create a new project and add a file, to see if this works...

Well, that didn't work... because there's another setting in File | New Projects Setup | Settings for New Projects... (you can also use actions modal) which looks absolutely the same but it is for new projects:

If you change "When files are created" to "Do not add", you won't be asked again, I'll promise 🤞️.

Annotating and highlighting epub using Logseq

2023-04-10T15:00:00Z

Photo by Kelly Sikkema on Unsplash

When possible, I'm trying to read books in epub format or as printed books. Most of my notes and journals live in Logseq.

So I was asking myself: "How could I bring my ebook highlights and notes to Logseq?"

While it isn't possible right now to load epub files into Logseq like you can do with PDF files, it is possible to reference your calibre notes and highlights - here's how:

First, highlight a section in a book and maybe also jot down some notes in a book using calibre:

Next, click the "Export" button at the bottom right and select "Markdown":

Now, click the "Copy to clipboard" button and paste the clipboard into your Logseq page:

As you can see, the highlighted section and the notes taken are now in your Logseq page for the book.

Did you spot the link 10.04.23 17:19? That's a deep link to your notes in calibre.

If you click the link, the book will be opened in calibre at the highlighted section. Neat, isn't it?

Of course, you could also convert the whole book to PDF using calibre and use the PDF annotation workflow I described recently.

Another option could also be to just automate the whole stuff by reading the metadata.opf calibre file and push it to your Logseq markdown files...

Learning Elixir

2023-04-10T20:00:00Z

Photo by Vlad Shagov on Gitu

I've decided to learn Elixir.

Not just poking a bit into the language but to be able to build full stack Elixir distributed applications and eventually SaaS.

I don't want to talk much about the why for now but you can find a hint or two on my social media channels.

This post aims to summarize the learning materials I've used so far and the building blocks I intend to learn about and use and I would be more than happy about your feedback and preferences here.

I'll categorize stuff a bit - here we go:

Language / General

Elixir official website
Elixir & Phoenix Fundamentals Full Course For Beginners on YouTube. Almost 6 hours non-stop Elixir and Phoenix learnings for free.
ElixirCasts [2023/04/17] - not everything is free but it's worth the money if you're serious abouit Elixir / Phoenix / OTP and GenServer
Elixir School - multilingual website packed with Elixir topics from basic to pro covering OTP, Testing, Data Processing and Storage
Elixir Forum - Discourse community for Elixir
Elixir Discord - Elixir community on Discord
Elixir Track on Exercism [2023/04/15 via Fernando Canizo] - Free Elixir exercises
ExDoc - A tool to generate documentation for your Elixir projects
hex - Package manager for the Erlang VM
Livebook - Share knowledge, explore code, visualize data, run machine learning models, and much more

Database

ecto - A toolkit for data mapping and language integrated query
postgrex - PostgreSQL driver for Elixir

Web Applications

Plug - A specification for composing web applications with functions
Bandit - A pure Elixir HTTP server for Plug & WebSock applications
Phoenix Framework - Framework written in Elixir which implements the server-side Model View Controller (MVC) pattern

Scheduling

Oban - Robust job processing in Elixir, backed by modern PostgreSQL or SQLite3

Event Sourcing / CQRS

saga - A dependency-free tool to run distributed transactions in Elixir, inspired by Saga pattern
commanded - Event Sourcing library for Postgres, EventStoreDB and In-memory

Messaging

Broadway - Build concurrent and multi-stage data ingestion and data processing pipelines with Elixir

Testing

ExUnit - Unit testing framework for Elixir.

Identity / Authentication

Pow - A robust, modular and extendable user management solution

Cloud

aws-elixir - AWS clients for Elixir

Elixir syntax highlighting for Logseq

2023-04-15T20:00:00Z

I'm journaling my Elixir learnings in Logseq.

Until today I've accepted the fact that LogSeq doesn't support Elixir syntax highlighting.

But today I came across the "Extensions plus" plugin for Logseq, which - besides some other features - adds syntax highlighting for Elixir:

Make sure to restart Logseq to make the plugin work.

Also, make sure "elixir" is checked in the plugin settings:

Installing the latest Elixir and Erlang versions on Xubuntu 22.04

2023-04-16T20:00:00Z

Photo by Mika Baumeister on Unsplash

After dabbling around with some Elixir courses I wanted to dig into the event sourcing sample named "franklin" by Mike Zornek.

Mike provides a README, so let's just run mix setup and see what happens:

** (Mix) You're trying to run :franklin on Elixir v1.12.2 but it has declared in its mix.exs file it supports only Elixir ~> 1.14.0

To be honest, I didn't care exactly about which versions of Elixir and Erlang I had installed using apt-get install erlang elixir and IEx experiments did work fine so far.

Ok, the latest stable versions seem to be Erlang 25.3 and Elixir 1.14.4.

Maybe mix was right...

After looking around at Elixir Forum, several people suggested using asdf which I've installed already (but I'll explain it from scratch anyway).

So, here we go - first uninstalling the old versions:

apt remove erlang elixir

Then install asdf:

git clone https://github.com/asdf-vm/asdf.git ~/.asdf

As I'm using oh-my-zsh / zsh, I've also enabled the asdf plugin in ~/.zshrc:

plugins=(
  asdf
  git
  zsh-autosuggestions
  zsh-syntax-highlighting
)

Next, I installed the erlang and elixir plugins for asdf:

asdf plugin add erlang https://github.com/asdf-vm/asdf-erlang.git
asdf plugin-add elixir https://github.com/asdf-vm/asdf-elixir.git

Then, some build dependencies are required:

sudo apt install libssl-dev automake autoconf libncurses5-dev

And finally, install Erlang:

export KERL_CONFIGURE_OPTIONS="--disable-debug --without-javac"
asdf install erlang 25.3

asdf_25.3 is not a kerl-managed Erlang/OTP installation
The asdf_25.3 build has been deleted
Extracting source code
Building Erlang/OTP 25.3 (asdf_25.3), please wait...
APPLICATIONS DISABLED (See: /home/alexzeitler/.asdf/plugins/erlang/kerl-home/builds/asdf_25.3/otp_build_25.3.log)
* jinterface     : Java compiler disabled by user
* odbc           : ODBC library - link check failed

APPLICATIONS INFORMATION (See: /home/alexzeitler/.asdf/plugins/erlang/kerl-home/builds/asdf_25.3/otp_build_25.3.log)
* wx             : No OpenGL headers found, wx will NOT be usable
* No GLU headers found, wx will NOT be usable
* wxWidgets was not compiled with --enable-webview or wxWebView developer package is not installed, wxWebView will NOT be available
*         wxWidgets must be installed on your system.
*         Please check that wx-config is in path, the directory
*         where wxWidgets libraries are installed (returned by
*         'wx-config --libs' or 'wx-config --static --libs' command)
*         is in LD_LIBRARY_PATH or equivalent variable and
*         wxWidgets version is 3.0.2 or above.

DOCUMENTATION INFORMATION (See: /home/alexzeitler/.asdf/plugins/erlang/kerl-home/builds/asdf_25.3/otp_build_25.3.log)
* documentation  : 
*                  xsltproc is missing.
*                  fop is missing.
*                  xmllint is missing.
*                  The documentation cannot be built.

Erlang/OTP 25.3 (asdf_25.3) has been successfully built
Cleaning up compilation products for 
Cleaned up compilation products for  under /home/alexzeitler/.asdf/plugins/erlang/kerl-home/builds

And Elixir:

asdf install elixir 1.14.4-otp-25 
==> Checking whether specified Elixir release exists...
==> Downloading 1.14.4-otp-25 to /home/alexzeitler/.asdf/downloads/elixir/1.14.4-otp-25/elixir-precompiled-1.14.4-otp-25.zip
% Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
Dload  Upload   Total   Spent    Left  Speed
100 6516k  100 6516k    0     0  12.2M      0 --:--:-- --:--:-- --:--:-- 12.2M
==> Copying release into place

franklin on  main [?] is 📦 v0.1.0 via 💧 v1.14.4 (OTP 25) 
❯ elixir --version                                               
Erlang/OTP 25 [erts-13.2] [source] [64-bit] [smp:8:8] [ds:8:8:10] [async-threads:1] [jit:ns]

Elixir 1.14.4 (compiled with Erlang/OTP 25)

Set the default versions:

asdf global elixir 1.14.4-otp-25
version 1.14.4 is not installed for elixir

asdf global erlang 25.3

Result:

Erlang/OTP 25 [erts-13.2] [source] [64-bit] [smp:8:8] [ds:8:8:10] [async-threads:1] [jit:ns]

Elixir 1.14.4 (compiled with Erlang/OTP 25)

Looks good and seems to work - however I may have done it wrong. If so, please let me know.

Parsing nginx logs with GoAccess and creating a HTML report in a cron job

2023-11-02T11:00:00Z

Photo by Luke Chesser on Unsplash

Gyula recently asked for a decent cookieless analytics tool on Twitter:

Okay. I don't wanna use Google analytics, I don't wanna anger my users with cookie popups, but wanna be GDPR compliant and I wanna have analytics on my website at the same time.

What should I do? Any recommendations?
— GYN (@gyulanemeth85) November 1, 2023

I suggested to use GoAccess to parse the nginx logs and create a HTML report and Hannes asked for a quickstart - so here we go.

Considering we're a running a Linux server with nginx and Docker, here's how to get started and our blog is static HTML generated with 11ty it is as easy as this to have a cron job running every day at 22:05 to create a HTML report of the nginx logs:

5 22 * * * cat /var/opt/deploy/logs/nginx/access.log | /usr/bin/docker run --rm -i -e LANG=$LANG allinurl/goaccess -a -o html --log-format COMBINED - > /var/opt/deploy/www/_site/report.html

The command in detail:

5 22 * * * - run the command every day at 22:05

cat /var/opt/deploy/logs/nginx/access.log - read the nginx access log

| - pipe the output to the next command

/usr/bin/docker run --rm -i -e LANG=$LANG allinurl/goaccess -a -o html --log-format COMBINED - - run the docker container with the GoAccess image and parse the nginx access log and create a HTML report

> /var/opt/deploy/www/_site/report.html - write the HTML report to the file system

The report:

Using aliases in scripts with zsh

2023-12-17T22:00:00Z

Photo by Ahmed Zayan on Unsplash

We often use shell aliases to make our life easier. However, when we try to use them in shell scripts (hence, subshells) it seems to get harder.

Let's say we have the following alias to run the AWS CLI in a docker container that is using the current directory as the working directory:

alias aws='docker run --rm -it -v ~/.aws:/root/.aws -v $(pwd):/aws amazon/aws-cli'

If we try to use this alias in a script, it will fail:

#!/bin/zsh

aws --profile my-aws-profile s3 cp s3://my-bucket/path/to/file .

This will result in the following error:

zsh: command not found: aws

There are a few things to know:

aliases are not expanded in non-interactive shells
functions are preferred over aliases in bash

So, let's try to use a function instead of an alias:

#!/bin/zsh

aws() {
  docker run --rm -it -v ~/.aws:/root/.aws -v $(pwd):/aws amazon/aws-cli "$@"
}

Now we could add the function to our .zshrc and source it and try to use it in our script and get new errors.

Long story short, there's a file named ~/.zshenv (if it doesn't exist, just create it) that is sourced on every invocation of zsh. So, we can add the function to this file and it will be available in our scripts.

aws() {
  docker run --rm -it -v ~/.aws:/root/.aws -v $(pwd):/aws amazon/aws-cli "$@"
}

Now we can use the function in our script:

#!/bin/zsh

aws --profile my-aws-profile s3 cp s3://my-bucket/path/to/file .

And it will work as expected 🎉.

Annotating Podcasts and MP3 files using Logseq

2023-12-23T20:00:00Z

Photo by Soundtrap on Unsplash

A while ago I posted how to annotate epub using Logseq. This time I'll show you, how to annotate Podcasts or more generic, MP3 files - using Linux.

First of all we need to create a .mp3 file from a Podcast.

I'm using the Podcasts browser extension (available for Firefox and Chrome) from here.

It looks a bit like a lightweight version of Spotify. You can search for Podcasts and subscribe to them. You can also download episodes and play them.

So you can open an episode:

And then you can download it by hovering over the episode and clicking the download button:

Open a terminal and change to the directory where you downloaded the episode. Then run:

ffmpeg -loop 1 -i ./cover.jpg \
       -i ./episode-12.mp3 \
       -vf "scale=1920:1080:force_original_aspect_ratio=decrease,pad=1920:1080:-1:-1:color=black,setsar=1,format=yuv420p" \
       -shortest -fflags +shortest \
       episode-12.mp4

Make sure to also have cover image named cover.jpg in the same directory. This will create a .mp4 file from the .mp3 file and the cover image.

Depending on the length of the episode and your machine, this can take a while, but you should get a result in under 10 minutes for a 20 minutes episode.

Now we can upload this video to YouTube, mark it as unlisted (so nobody beside you can see it until they get the link) and use the YouTube video to annotate it using Logseq (just past the video link into Logseq).

You can add a timestamp by stopping the video at the desired position and then typing /timestamp in the Logseq editor. This will show the menu where you can pick the "Embed YouTube timestamp" option with the number of seconds at which you paused the video.

As said, make sure to have an background image added, otherwise the video will not be processed by YouTube.

Of course, you can also create .mp4 files from .mp3 files on macOS using iMovie (and I guess there's something similar available on Windows, too).

And of course, if the Podcast provides a YouTube version of the episode, you can use that instead of creating a video from the audio file and uploading it to YouTube.

The Podcast extension also offers a paid service to transcribe the audio file. I haven't tried that yet because I want to annotate in my own words. I just need the timestamps feature.

I also tried Snipd but their transcription service is not available for German language yet.

Setting Displays to monochrome / grayscale (Saturation 0) on Xubuntu / XFCE

2023-12-25T20:00:00Z

Photo by Chris Ried on Unsplash

For some tasks like writing I prefer to have my displays set to monochrome / grayscale. This is how I do it on Xubuntu / XFCE.

There are several solutions out there that use xrandr or ddcutil but none of them worked for me. I'm using Xubuntu 22.04.2 LTS on a late 2012 Mac mini for some tasks.

So here is how you would do it using xrandr:

xrandr --output HDMI-3 --set Saturation 0

HDMI-3 is the name of my display.

You can get the name of your display by running xrandr without any arguments.

Connected displays will be listed like this:

HDMI-3 connected 1920x1200+1920+0 (normal left inverted right x axis y axis) 518mm x 324mm

The solution that actually worked for me was to use libvibrant and its source can be found on GitHub.

It's said to be build and installed this way:

mkdir build
cd build
cmake ..
make
sudo make install

However, I had to do few more things to get it working:

mkdir build
cd build

# fixes: Could not find X11
sudo apt install libx11-dev 

# fixes: The RandR library and headers were not found
sudo apt install xorg-dev libglu1-mesa-dev

# fixes: fatal error: NVCtrl/NVCtrlLib.h: No such file or directory
sudo apt install libxnvctrl-dev

cmake ..
make

# fixes: libvibrant.so.1 cannot open shared object file
sudo /sbin/ldconfig -v*

sudo make install

After that I was able to run vibrant-cli and it worked like a charm:

vibrant-cli HDMI-3 0
vibrant-cli DP-1 0

To reset the saturation to 100%:

vibrant-cli HDMI-3 1
vibrant-cli DP-1 1

Running this will make it look even better:

xgamma -gamma 0.8

If you create a .desktop entry for both commands, you easily run them using a launcher like Albert:

Rotating nginx logs using Docker Compose and logrotate

2023-12-30T15:00:00Z

Photo by Sigmund on Unsplash

If you're running nginx in a Docker container, you might want to rotate the logs. Here's how to do it using Docker Compose and logrotate.

Consider the following docker-compose.yml:

version: '3.7'

services:
  nginx:
    image: nginx:1.19.6-alpine
    ports:
      - 80:80
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
      - ./logs:/var/log/nginx

The default location for nginx logs is /var/log/nginx. We're mounting the logs directory from the host into the container. This way, we can access the logs from the host.

We can now use logrotate to rotate the logs. Create a logrotate configuration file called that's called like your service in /etc/logrotate.d/, in this case nginx:

touch /etc/logrotate.d/nginx

Add the following content to the file:

/var/opt/deploy/logs/*.log {
  daily
  missingok
  rotate 31
  dateext
  compress
  delaycompress
  notifempty
  sharedscripts
  postrotate
    cd /var/opt/deploy \
      && /usr//bin/docker compose kill -s USR1 nginx
  endscript
}

This will rotate the logs daily, keep 31 days of logs, compress the logs, and send a USR1 signal to the nginx process in the container. This will cause nginx to reopen the log files.

The dateext option will append the date to the rotated log files. For example, access.log will become access.log-20231230.

Make sure to match the path to your logs. In this case, the logs are located in /var/opt/deploy/logs/ on the host. The logs are mounted into the container at /var/log/nginx/. The logs are located in /var/log/nginx/ in the container.

Also make sure to match the path to your docker-compose.yml. In this case, the docker-compose.yml is located in /var/opt/deploy/ on the host.

The postrotate script will change into the directory where the docker-compose.yml is located and send the USR1 signal to the nginx process in the container. This will cause nginx to reopen the log files.

The USR1 signal is sent to the nginx process in the container using docker compose kill. The USR1 signal is not sent to the container itself, but to the process running inside the container. The process running inside the container is nginx.

You can test the log rotation by running logrotate manually:

logrotate -f /etc/logrotate.d/nginx

And that's it. Your nginx logs will now be rotated daily, compressed, and kept for 31 days.

Listening to HTMX HX-Trigger response header events from Alpine.js

2024-02-11T00:00:00Z

Photo by Vincent van Zalinge on Unsplash

HTMX and Alpine.js are a great combination.

Here's how to listen to HTMX HX-Trigger response header events from Alpine.js.

HTMX allows you to listen for Events from the HTTP Response using the HX-Trigger response header (the last line matters) like this:

HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Date: Sat, 10 Feb 2024 22:46:58 GMT
Server: Kestrel
Transfer-Encoding: chunked
HX-Trigger: product-added-to-shopping-cart

This indicates that a product has been added to the shopping cart.

HTMX itself can respond to this type of "events" like this:

<div hx-get="/shopping-cart-preview"
     hx-target="#shopping-cart-preview"
     hx-trigger="product-added-to-shopping-cart from:body"
     id="shopping-cart-preview"></div>

This will reload the shopping cart preview.

No we might want to display a toast or the like using Alpine.js when the product has been added.

HTMX is publishing the events it receives from the server as global events, so you can just listen to it from vanilla JavaScript:

<script type="text/javascript">
  document.addEventListener('product-added-to-shopping-cart', event => {
    console.log('product-added-to-shopping-cart')
  })
</script>

Alpine.js allows you to listen for events on the global window object like this:

<div @some-event.window="console.log('some-event was dispatched')">...</div>

So we can listen to product-added-to-shopping-cart using Alpine like this:


<div x-data="{showToast:false}"
     @product-added-to-shopping-cart.window="showToast = true">
    ...
</div>

Straight forward and simple, yet asked quite often.

Dealing with C# records in ASP.NET Core model binding

2024-02-21T18:00:00Z

Photo by Viktor Forgacs on Unsplash

C# records are a great addition to the language. They are immutable, have value semantics, and are great for modeling data. But when it comes to model binding in ASP.NET Core, things are getting a bit more complicated. Let's see how we can deal with C# records in ASP.NET Core model binding.

What are C# records?

C# records are a new feature in C# 9. They are a reference type, but they have value semantics. This means that they are immutable and can be compared by value. They are great for modeling data, and they are a great addition to the language.

Here is an example of a C# record:

public record Person(string FirstName, string LastName);

In this example, we have a Person record with two properties: FirstName and LastName.

Model binding in ASP.NET Core

Model binding is the process of mapping data from an HTTP request to an object in your application. It is a fundamental part of building web applications, and it is used to handle form submissions, query string parameters, and other types of data.

In ASP.NET Core, model binding is done automatically by the framework. When you create a controller action that takes a parameter, the framework will try to bind data from the request to that parameter.

Here is an example of a controller action that takes a Person parameter:

[HttpPost]
public IActionResult CreatePerson(Person person)
{
    // ...
}

In this example, the framework will try to bind data from the request to a Person object. This is done automatically by the framework, and it is a very powerful feature.

Dealing with C# records in ASP.NET Core model binding

At a first glance, everything seems to be easy with C# records. But when it comes to model binding in ASP.NET Core, things are getting a bit more complicated.

Now there are two issues with C# records and model binding in ASP.NET Core:

The model binding needs a parameterless constructor
If you want to translate property names or set display error messages, you need to use the Display and Required attributes.

The shortest way (I know) to have a parameterless constructor while maintaining the positional constructor is this one - I want to avoid embrace a class like style:

public record Person(
  string? FirstName,
  string? LastName
)
{
  public Person() : this(
    null,
    null,
  )
  {
  }
}

The Display and Required attributes are used to set display error messages and translate property names. Here is an naive approach to use them:

public record Person(
  [Display(Name = "First Name")]
  [Required(ErrorMessage = "The first name is required")]
  string? FirstName,
  [Display(Name = "Last Name")]
  [Required(ErrorMessage = "The last name is required")]
  string? LastName
)
{
  public Person() : this(
    null,
    null
  )
  {
  }
}

This won't work, because the Display and Required attributes are not recognized by the model binding. You need to do it that way:

public record Person(
  [property:Display(Name = "First Name")]
  [property:Required(ErrorMessage = "The first name is required")]
  string? FirstName,
  [property:Display(Name = "Last Name")]
  [property:Required(ErrorMessage = "The last name is required")]
  string? LastName
)
{
  public Person() : this(
    null,
    null
  )
  {
  }
}

The reason for this is, without the property: prefix, the attributes are not recognized by the model binding because FirstName and LastName are not properties of the Person but constructor parameters. By adding the property: prefix, the attributes are emitted for generated properties instead and the model binding can recognize them.

find_executable: checking for pg_config... no when installing pg Ruby gem on Ubuntu

2024-06-26T14:00:00Z

Photo by Dayne Topkin on Unsplash

Recently I've been tipping my toes into Ruby/Rails water and I wanted to give the Rails Event Store a try. When I tried to install the gems on Ubuntu, I got an error:

find_executable: checking for pg_config... no

when installing the pg Ruby gem on Ubuntu. Here's how I handled it.

The reason for that is quite obvious: the installer tries to refer a library named pg_config which doesn't exist on my system.

It's also quite obvious it will be included in the postgresql package, but I'm running Postgres in Docker for ages, so I don't want to install Postgres just for the sake of this.

Long story short, just install the following packages using apt:

sudo apt install postgresql-client libpq5 libpq-dev

And with that installed you can install the Rails Event Store dependencies without installing Postgres.

Selecting and copying text without border in Zellij using the keyboard

2024-09-28T07:00:00Z

Photo by Michelle Ding on Unsplash

Thanks to Omakub I got introduced to Zellij:

Zellij is a terminal workspace. It has the base functionality of a terminal multiplexer (similar to tmux or `screen) but includes many built-in features that would allow users to extend it and create their own personalized environment.

This is how a Zellij window could look like, showing the output from /var/log/syslog

Now we want to copy this part (in the last line of the output) using the keyboard only:

2024-09-28T06:56:13.403642+02:00 aetron kernel: [UFW BLOCK] IN=enp14s0

First press CTRL+SHIFT+SPACE to enable the vim mode in Zellij.

Then navigate to the first char you want to copy using the cursor key:

Now press v to enable vim Visual Mode (nothing will change visually).

Now move the cursor to the right until the char you want to be copied last.

Finally, press y and this will yank you selection and it will be available in your clipboard for further usage.

Great, but there's one issue: multiline selection:

As you can see, the green border is included in the selection and this will mess up you copied content.

But there's a solution for that:

Press CTRL+p, then z to disable the border before you're entering vim Mode:

Now you can copy multiple lines without including the border.

If you want to get the border back, press CTRL+p, then z again.

Instead of using Visual Mode, you can also enable Visual Line Mode by hitting V instead of v and that will allow you to just select full lines by moving the cursor up and down.

Multiple feeds with 11ty

2024-11-19T12:00:00Z

You can create multiple feeds using 11ty.

For example, if you want to split Posts and TILs (Today I Learned).

Create a new collection til in .eleventy.js:

eleventyConfig.addCollection("til", function(collectionApi) {
  return collectionApi.getFilteredByTag("til");
});

Create a new til.njk template for the feed.

---json
{
  "permalink": "til.xml",
  "eleventyExcludeFromCollections": true,
  "metadata": {
    "title": "Alexander Zeitler | TIL",
    "url": "https://alexanderzeitler.com/",
    "feedUrl": "https://alexanderzeitler.com/til.xml",
    "author": {
      "name": "Alexander Zeitler",
      "email": "alexander.zeitler@pdmlab.com"
    }
  }
}
---
<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <title>{{ metadata.title }}</title>
  <subtitle>{{ metadata.subtitle }}</subtitle>
  <link href="{{ metadata.feedUrl }}" rel="self"/>
  <link href="{{ metadata.url }}"/>
  <updated>{{ collections.til | rssLastUpdatedDate }}</updated>
  <id>{{ metadata.url }}</id>
  <author>
    <name>{{ metadata.author.name }}</name>
    <email>{{ metadata.author.email }}</email>
  </author>
  {%- for post in collections.til %}
  {% set absolutePostUrl %}{{ post.url | url | absoluteUrl(metadata.url) }}{% endset %}
  <entry>
    <title>{{ post.data.title }}</title>
    <link href="{{ absolutePostUrl }}"/>
    <updated>{{ post.date | rssDate }}</updated>
    <id>{{ absolutePostUrl }}</id>
    <content type="html">{{ post.templateContent | htmlToAbsoluteUrls(absolutePostUrl) }}</content>
  </entry>
  {%- endfor %}
</feed>

Tag your posts with til:

---
title: 'Multiple feeds with 11ty'
date: 2024-11-19T12:00:00
layout: default
tags: til
---

How to handle PII using Marten

2024-11-20T23:30:00Z

Babu has created a series of posts on how to handle PII using Marten:

Personally Identifiable Information masking in Marten documents using partial update/patching

Encrypting Personally Identifiable Information at rest in Marten documents

Encrypting and crypto-shredding of PII data in Marten documents using HashiCorp Vault

ASP.NET Core TagHelpers: underrated feature of an underrated framework

2024-11-21T18:00:00Z

The State of ASP.NET Core MVC

ASP.NET Core TagHelpers have been around for quite some time but only few people seem to like them. Here's why I think they're awesome.

ASP.NET Core - and even more: MVC - is one of the most underrated Web Frameworks. This might be an unpopular opinion these days when Single Page Apps, JSX/TSX, Next.js and SSR are all the rage.

Even Microsoft thinks they need to move away from the old stuff and build shiny new things like Blazor, which - surprise, surprise - suddenly was given a plain SSR mode.

ASP.NET Core Tag Helper Basics

Razor Syntax (the language used in MVC Views and Razor Pages) has been around for ages, and it's a powerful language.

You can have iterators, C# code blocks, includes (partials) and you can inject everything from the IoC container.

And - to get back to the beginning of this post: you can have tag helpers.

TagHelpers can be used at the tag level (build a new HTML tag) or at the attribute level (add attributes to existing HTML tags).

The ladder is heavily used by the great HTMX TagHelpers library for .NET maintained by Khalid.

This also shows the great IDE support for Razor and TagHelpers in JetBrains Rider. "Go To Definition" and "Find Usages" works great as well as refactoring.

A popular example for HTML Tag TagHelpers is the partial Tag Helper provided by ASP.NET Core itself:

<partial name="SomePartialRazorView" model="SomeModel" />

Using TagHelpers, we can either create HTML Tags or attributes that encapsulate functionality.

A simple TagHelper that creates a custom element could look like this:

using Microsoft.AspNetCore.Razor.TagHelpers;

namespace MyApp.TagHelpers

public class MyTagHelper : TagHelper
{
    public string Text { get; set; } 
    public int Number { get; set; } 
 
    public override void Process(TagHelperContext context, TagHelperOutput output)
    {
        for (int i = 0; i < Number; i++)
        {
            output.Content.AppendHtml($"{Text}<br/>");
        }
    }
}

The TagHelper gets registered in ViewImports.cshtml:

@addTagHelper MyApp.TagHelpers.MyTagHelper, MyAssembly

Or we can just register all TagHelpers defined within our app:

@addTagHelper *, MyAssembly

The TagHelper can be used in any Razor View like this:

<my-tag-helper text="Some text" number="5"></my-tag-helper>

The generated HTML output will be this:

Some text<br/>
Some text<br/>
Some text<br/>
Some text<br/>
Some text<br/>

Razor Views in Tag Helpers

What has been holding me back to make more use of Tag Helpers has been the need to build the HTML manually, sort of and the lack of ability to render Tag Helper in a nested style or having child content at all.

After some research I found out that it's actually possible to have child content, nest Tag Helpers and even better: have Razor Views for Tag Helpers instead of creating the content from strings. Having Razor views at hand is especially useful when using Tailwind CSS which builds the CSS file on the fly.

Long story short: this is what a base class for a Tag Helper, that loads its content from a Razor View, could look like:

public abstract class RazorTagHelperBase<TModel> : TagHelper
{
  [HtmlAttributeNotBound] [ViewContext] public ViewContext ViewContext { get; set; }
  private IHtmlHelper _htmlHelper;

  public RazorTagHelperBase(
    IHtmlHelper htmlHelper
  )
  {
    _htmlHelper = htmlHelper;
  }

  private string _partialName;
  private TModel? _model;
  private bool _allowChildContent;

  protected async Task<IHtmlContent> RenderPartial<T>(
    [AspMvcPartialView] string partialName,
    TModel model
  )
  {
    (_htmlHelper as IViewContextAware).Contextualize(ViewContext);

    return await _htmlHelper.PartialAsync(partialName, model);
  }

  /// <summary>
  /// 
  /// </summary>
  /// <param name="partialName"></param>
  /// <param name="model"></param>
  /// <param name="allowChildContent"></param>
  protected void SetPartialName(
    [AspMvcView] [AspMvcPartialView] string partialName,
    TModel? model,
    bool allowChildContent = false
  )
  {
    _partialName = partialName;
    _model = model;
    _allowChildContent = allowChildContent;
  }

  public override async Task ProcessAsync(
    TagHelperContext context,
    TagHelperOutput output
  )
  {
    try
    {
      (_htmlHelper as IViewContextAware)?.Contextualize(ViewContext);

      IHtmlContent content;

      string error;

      if (_allowChildContent)
      {
        var childContent = await output.GetChildContentAsync();
        var children = childContent.GetContent();
        if (_model is IHasChildContent modelWithChildContent)
          modelWithChildContent.ChildContent = children;
        else
          throw new InvalidOperationException(
            $"Model of type {typeof(TModel).Name} does not implement IHasChildContent"
          );

        content = await _htmlHelper.PartialAsync(_partialName, modelWithChildContent);
      }
      else
      {
        content = await _htmlHelper.PartialAsync(_partialName, _model);
      }

      output.SuppressOutput();
      output.TagMode = TagMode.StartTagAndEndTag;
      output.PreContent.AppendHtml(content);
    }

    catch (Exception exception)
    {
      output.PreContent.AppendHtml(await _htmlHelper.PartialAsync("RazorTagHelperBase", exception));
      Console.WriteLine(exception);
    }
  }
}

All you have to do is to create a class that derives from this class, define a model class or record type.

If you want to allow the Tag Helper to render child content, your model has to implement this interface:

public interface IHasChildContent
{
  string? ChildContent { get; set; }
}

Let's assume we're building a Tag Helper that renders a "thread" for discussions which we would use like this:

<thread items="@Model.Items">
   
</thread>

The C# class:

public class Thread
{
  public string Title { get; set; }
  public List<ThreadItem> Items { get; set; } = new();
}

public class ThreadTagHelper : RazorTagHelperBase<Thread>
{
  [HtmlAttributeName("title")] public string Title { get; set; }
  [HtmlAttributeName("thread-items")] public List<ThreadItem> Items { get; set; } = new();

  public ThreadTagHelper(
    IHtmlHelper htmlHelper
  ) : base(htmlHelper)
  {
  }

  public override Task ProcessAsync(
    TagHelperContext context,
    TagHelperOutput output
  )
  {
    var thread = new Thread
    {
      Title = Title,
      Items = Items
    };
    SetPartialName("ThreadTagHelper", thread);
    return base.ProcessAsync(context, output);
  }
}

The Razor view:

@model ThreadTagHelper.Thread

<section aria-labelledby="notes-title">
  <div class="bg-white shadow sm:rounded-lg sm:overflow-hidden">
    <div class="divide-y divide-gray-200">
      <div class="px-4 py-5 sm:px-6">
        <h2 class="text-lg font-medium text-gray-900"
            id="notes-title">
          @Model.Title
        </h2>
      </div>

      @{ var index = 0; }
      @foreach (var threadItem in Model.Items)
      {
        <thread-item thread-item="@threadItem"></thread-item>
        @if (index + 1 < Model.Items.Count)
        {
          <div class="relative pb-4">
            <span aria-hidden="true"
                  class="absolute top-1 left-6 -ml-px h-full w-0.5 bg-gray-300"></span>
          </div>
        }
      }

    </div>
  </div>
</section>

As you can see, the Razor view itself contains another Tag Helper <thread-item>.

Tag Helpers for View Composition in Distributed Systems / Vertical Slice Architecture

Two days ago, Khalid posted about creating an "Island" TagHelper, which loads a view fragment on demand.

This is quite similar to what I'm using in my Vertical Slice Architecture solutions for View Composition.

Different contexts / features are providing self-contained components, which provide fragments of the UI:

While the parts highlighted yellow in the screenshot, are provided by a Catalog Context (Service), the parts highlighted blue are provided by a Pricing Context (Service).

In my case, the components are implemented using TagHelpers as shown above.

Depending on the level of Coupling/Decoupling your .NET Solutions/Projects have/allow, they can reside in a single project, or they can reside in shared projects and be imported in the _ViewImports.cshtml as shown above as well.

Also depending on your coupling/decoupling model, the Tag Helpers can either call services via HTTP (as Khalid has shown) to get their views, or they access their contexts in process and render the result using Razor views as shown above.

That way you can have decoupled, self-contained components in your server side rendered UI (which is the place where the coupling should actually happen).

And that's the major reason why I think that ASP.NET Core TagHelpers are one of the most underrated features of a highly underrated web framework.

Even more, since JetBrains Rider - whose Razor support is top-notch - can now be used for free for non-commercial projects.

11ty redirects

2024-11-22T12:30:00Z

Sometimes you want to change urls in 11ty without breaking them.

There are several posts out there explaining how it can be done when your site is running using Netlify, but there's little content how to do it with plain 11ty.

Lucky me, I found this post, which shows a solution by introducing a new 11ty template named eleventy-redirect.njk in the root folder.

In your posts (the ones to which the redirect should point to), add this to your front matter (given your posts are in the articles folder):

---
redirect_from: /articles/my-old-url
---

Make sure to delete the old directory/files from which the direct should happen.

"CRUD APIs are poor design" - a follow up

2024-12-05T12:00:00Z

Derek's statement...

The gist of Derek's video, which he published yesterday, is this:

Typical API Design consists of building around database records and Create Read Update Delete. Making nothing more than a UI or HTTP API around a database. But that database schema was driven by business processes. But if those business processes don't live in your system, then trying to evolve your schema can be challenging. Instead of modeling data structure, model business processes and the data behind them.

... and my follow-up

As with most of Derek's videos, I completely agree with him.

Yet, I want to add one or two thoughts.

Back in the days, when I was young, we only had what's called "server side rendering" (SSR) these days.

When HTTP JSON APIs and Single Page Applications took off almost 15 years ago, this seemed to be the promised land - even more so with the advent of Microservices.

And yet here we are today, with failed projects, drowning in either technical debt or complexity - or both.

While a lot of things we've done as developers (and architects) in the past, have been doubted, CRUD still is accepted as the default storage pattern for most applications.

At the other side of the applications, having an HTTP JSON API, also has become the default.

Be it CRUD or HTTP JSON APIs: there has been built a ton of tooling around both of them, often to handle the complexity which these patterns are causing.

But to be honest: I think this is a dead end.

While it is compelling to sell tools, that deal with complexity and other issues caused by CRUD and HTTP JSON APIs, it will never solve the root cause.

The root cause - in my opinion - is trying to solve business problems with the least amount of business understanding and the biggest amount of technology possible. It may sound like an exaggeration, but I've seen it more than often in real world projects.

"So, what's your solution?" one might ask.

I wouldn't call it "solution" but I'm explaining my approach.

In short: less complexity and more explicit code.

What does this mean in practice?

Less complexity

By "less complexity", I mean choosing a boring stack - in my case that's ASP.NET Core MVC.

It's production tested for ages. Especially when building something new - in terms of business model - the more code you create in the beginning, the more effort you have to put in maintenance and changes. And when exploring a new business model, you will have a lot of changes.

You're creating legacy code with no need to do so.

"Will it scale" is the wrong question if you have no customers.

And if you do get more customers, how do you scale in terms of business and features, if nobody knows why this data even exists and who's changing it?

"API first" has been all the rage for years, but from my experience a lot of APIs being built are used only by the product vendor in the SPA frontend itself.

So why not start with a simple sever side rendered UI in the beginning?

Due to lower ceremony (think AuthN/AuthZ, mapping data and whatnot), you can focus on the business processes (yes, that's what earns the money - not the code).

To gather a good understanding of the processes, I would recommend using techniques like Event Storming or Event Modeling (my personal choice).

That way you get an understanding of which data belongs together (coupling/cohesion), hence should exist in the same context or vertical slice.

Building the UI for these slices with minimal effort as described above, you'll notice that data that is - and should be - coupled will be placed closely together in the UI as well.

Which brings us back to APIs: your server side rendered web front end is the first implementation ("representation") of your API - it's just serving HTML instead of JSON.

Now you might tell me: "but its structure is completely different from what my JSON API would be".

Yes, because people are building JSON APIs around entities instead of processes.

Now instead, think about providing a JSON API that looks exactly what your HTML forms or tables (lists, grids) look like - just in JSON.

Hint: You don't need to re-invent the wheel here: Hypermedia has got you covered - give HAL, HAL forms and real REST APIs a chance.

And maybe, maybe out of sudden there's no need for GraphQL any longer, because data that belongs together isn't spread across services/contexts/slices.

Explicit code

Now you might ask another question: "but I have so many different views, how do I get all the entity data together?"

The answer is: don't use one model to rule them all.

Create dedicated models for specific views, because these are only representations of your data.

Which brings us to the next question: "what is my data actually?"

Data doesn't "just" exist - it comes to life by filling forms to meet the needs of business capabilities and processes.

Calling it "filling forms" doesn't do it justice - you're completing a step in a process.

In terms of business, this step has a meaning and most of the time a name already.

Examples are "add item to cart", "book a room", "place order" - you name it.

Now we're closing the loop with Derek's video:

Model the events that have happened, after you completed the steps mentioned above successfully.

You'll end up with "Item added/removed to/from cart", "Room booked", "Order placed".

Store these events instead of the state of a cart, room bookings or orders.

Now you can start asking questions like the business wants it to do:

"Which items have been removed from the cart before an order has been placed?"
"Which options (beamer, whiteboard etc., room size) have been chosen/unselected before the room booking happened?"

Because business wants to understand which products don't sell and why.

The immutable truth is in your persisted events that will be there forever (if you want it to) and anything else are just different representations of the truth.

Combined with Event Modeling you make it very explicit where your data comes from - properties for some state don't just exist - they're caused by a command and even more important: they're persisted in one or more events - now you are able to point exactly at a diagram or in your code and tell when a property comes to life and when it gets changed - and on top you get the reason for it.

Being able to evolve your code is the only way to keep your business up in the long term. By knowing where your data is caused and modified, you're able to delete or change code (evolve) without being afraid of breaking things for your users when making required changes.

So, in addition to Hypermedia/HAL, you might consider Event Sourcing instead of CRUD.

And that's my thoughts around this topic.

DBeaver supports projects

2024-12-19T02:00:00Z

Just noticed DBeaver has projects, you can organize your connections.

You can start a new project via File/New:

You pick a custom project location by unchecking "Use default location":

The active project can be selected here:

How systems should be built

2025-01-03T12:00:00Z

How systems should be built: easy to change when business changes.

How most systems are built: easy to change when tech changes.

Reality: business changes much more frequently than the technology.

Why I switched from ASP.NET Core to Ruby on Rails

2026-01-06T05:00:00Z

If you have been following me on X for the past few months, you might have noticed that I've moved on from ASP.NET Core to Ruby on Rails. Some people asked why...

TL;DR

If you are looking for a detailed technical - or even performance - comparison between Ruby on Rails and ASP.NET Core, this article is not for you - it only contains opinions, learnings and stories from everyday usage.

Setting the stage

Back in early 2015, I've said Farewell.

It was a farewell to Windows and .NET for technical reasons.

Windows felt bumpy and .NET wasn't available on Linux (I know there's been Mono).

So I went along with Linux and Node.js for several years.

Time moved on and somewhere between 2020 and 2021 I gave .NET - now fully cross platform - another shot. This would not have happened without JetBrains Rider, btw.

I've started building some stuff using C# and F# and ASP.NET Core, of course.

Stars really seemed to align again, when I discovered Marten and Wolverine for Event Sourcing and Messaging.

With ASP.NET Core MVC, HTMX, Marten, Wolverine, Vertical Slice Architecture and Rider I've enjoyed software development like I didn't for ages.

I've written almost 30 articles for a major German .NET magazine during that time about these topics.

Bright stars and dark clouds

[Narrators voice: Scene 1]

However, there was an elephant in the room: Microsoft.

Back around 2018, I had the questionable joy of dealing with Microsoft Germany in a customer project.

After finishing it, I've decided to never do anything related to Microsoft Azure again.

"Why is this important?" you may ask.

While .NET is open source software (OSS) at first sight, it is still tied to Microsoft. Back in the days when it has been Windows only, it has been a vehicle driving sales for Visual Studio and kept people on Windows.

As cloud has become Microsoft's major business, .NET has aimed at getting developers to use Azure for their deployments.

Not by making it the only choice, but by making it the default and easy one - and nobody gets fired for choosing Microsoft.

As I've been using Docker since it's early days, this hasn't been much of an issue for me - I could re-use my deployment scripts from Node.js with almost zero changes - give me a VPS and I'm good to go.

While I could ignore most of this stuff, it has always been around - the well known ".NET Drama" like not releasing the debugger as open source, constantly re-inventing successful community packages and stuff like that.

Speaking of re-inventing stuff: Microsoft has a knack for building UI frameworks nobody likes (except the chosen few). Be it Silveright, MAUI or whatever year you pick.

Back in 2018, Microsoft announced "Blazor", their latest idea of how component based web development should be done. Driven by the pressure of client side frameworks like React and whatever Next.js is, they started building something similar based on .NET and Web Assembly.

Over the years this has evolved into something with several hosting models.

I don't know what's its current state, but several people tried to make it work with libraries like HTMX and it seemed to be a PITA to me - do it the way Microsoft invented it or just stick with ASP.NET Core MVC.

I did the latter because "what should possibly go wrong?". I was wrong. Over time, Microsoft started to make "optimiziations" in ASP.NET Core which started to more or less break stuff in MVC.

Furthermore, it is virtually no longer actively maintained, as can be seen from the GitHub issues.

[Narrators voice: Scene 2]

With short breaks, Linux has been my daily driver (speaking of Desktop OS) since mid 2014 - Ubuntu most of the time.

Ubuntu has become more and more mainstream and at some point they've decided to switch to Gnome Desktop as their default.

While it became more polished, it also became less of a developer OS and it felt like the Desktop got in my way when I wanted to do things.

Mid-2024 Linux got a new advocate: David Heinemeier Hannson (DHH) came up with Omakub, "An Omakase Developer Setup for Ubuntu 24.04+".

It has been a nice match for my new TUXEDO Desktop. At least for while...

While Alacritty and Tactile have been some nice improvements for Window management, it felt sort of unnatural with Ubuntu.

As it turned out, DHH felt the same and Mid-2025 he came up with the real banger: Omarchy:

A super polished Linux Desktop environment for developers based on Arch Linux and Hyprland, a tiling window manager.

It has hit like a bombshell, and it is unlikely that you have not already heard about it.

It's the daily driver on my Gen5 ThinkPad L14 since then and I've installed it on several outdated Apple hardware like a Late 2012 Mac mini and a Mid-2012 MacBook Pro.

It also got me back to vim as my primary editor by making neovim the default for a lot of stuff in Omarchy.

I even started using it for ASP.NET Core development and I already started to write a blog post on how to do full time ASP.NET Core development using neovim in summer 2025.

[Narrators voice: Scene 3]

I've been a software developer most of my career but for some reasons I became a CEO in manufacturing by the end of 2024.

At that time, the company has been running on a typical stack:

Windows 10
Microsoft Office
sage business software
SolidWorks 3D CAD

While I could accept things, I haven't been happy with it.

The whole stack has been maintained by several companies via support contracts.

Side note: back in the late 90ties I've been a sage Partner myself so I know a thing or two about the software in question.

Apart from the relationship with the system vendor, which is responsible for the network infrastructure, Windows and Office, user satisfaction with support is rather low.

Given all the "you're not the customer, you're the product" features in Windows 11 and Office creeping in, I've avoided the migration from Windows 10 for the company as long as I could.

This paid off when Microsoft announced that Windows 10 support would be extended for another year in the EU.

Speaking of SolidWorks: you get more support from the forums on the Internet than from official Partners you're paying for it.

Regarding sage, things got worse when we tried to pull some data out of it and eventually getting rid of the software at all.

Back in the days, this has been a no-brainer using pure SQL until 2008 and later DCOM.

Trying this in 2025, DCOM has stopped working - as it turned out, libraries haven't been installed on intent (make the customer pay as often as you can).

They tried to sell us a "project" where our "requirements would be evaluated" and then the typical dance would start - for a problem that could be purely solved using a single SQL SELECT statement until 2008 or roughly 10 lines of C# Code via DCOM.

When I discovered this on a Saturday in mid-September 2025, the topic of proprietary ecosystems was finally dead to me.

On that day, I decided that we would end our collaboration with all of the aforementioned software manufacturers by mid-2026 and also replace Windows entirely with Linux - remember: we're a manufacturing company, not a software business.

Omakase

As mentioned earlier, Omakub and Omarchy are based on the principle of Omacom.

Omacom stands for Omakase Computing. The word Omakase means "I'll leave it up to you" or "chef's choice" in Japanese.

It's the idea that most people don't actually know what they want, at least not at first. That they're better off getting something beautifully curated and integrated from someone they trust to make competent, tasteful decisions rather than suffer from the paradox of choice.

By watching DHHs videos on Omarchy, I found out that Ruby on Rails has been following this principle for a long time already.

As I've been happy with the chef's choices in Omarchy, I've decided to take a closer look at Rails.

I managed to completely ignore it until this time - I didn't even look at it when I was looking for an cross platform alternative to ASP.NET back in 2014.

Setting Rails up was a no-brainer thanks to mise which is the default in Omarchy to manage dev tools.

After reading some Rails Guides on their website, I wanted to get results fast, so I opted for AI ("Vibe Coding") to build some applications I would have built using ASP.NET Core anyway using Rails.

Mid-September 2025 I've been using ChatGPT most of the time and vibe coding a Rails app that would use Postgres and Tailwind started off quite well but at some point it got me bad vibes.

Good Vibes

As I've posted some of my progress on X, people started to recommend Claude instead of ChatGPT and now things really took off.

Within a few days I've built an end-to-end app to track material requirements from the shop floor, incoming goods and invoice verification. This included stuff like stamping PDFs for approval.

One thing I wanted to verify early has been deployments and this is where Rails and the "majestic monolith" you build really shines.

When creating a new Rails app, it also initializes Kamal - Omakase for deployments based on Docker.

After providing a minimal set of credentials and settings I got the app deployed on our staging VM in our Proxmox setup.

That has been the time when I was hooked already.

But I wanted to build more - on the one hand, to continue testing Rails, and on the other, because I needed alternatives to the existing software for the reasons mentioned above.

We've been using Word for product documentation - customers don't want Markdown when they purchase industrial machinery or equipment.

As I've been looking for an alternative for this process, I came along AsciiDoc. So I made a manual proof of concept for one of our machinery documentation first.

Next, I wanted to have a platform to manage documentations (versions, text modules etc.).

So I set up another Rails app using Claude and a few days later we've been using this already to create a documentation for a just finished machinery project.

The Rails app at this time already had HTML/PDF live preview and automated translation using the DeepL API. You could also manage the assets like images and pictograms (via Rails ActiveStorage).

Sometimes the universe sends you a message.

In October, the employee who prepares the time sheets for payroll accounting fell ill.

I then did the payroll stuff and realized how little the current software supported us in this process.

This made it clear what would happen next: software for time tracking and reporting using Rails.

This time, however, using Event Sourcing.

I picked Rails Event Store and let Claude do it's job.

Long story short: since December timesheets run on Rails.

So as not to bore you further with apps, here is a short list of what else I have built with Rails and is already in use at our company:

Task management with completion tracking (uses SSE for notifications, for example)
App for inventory recording, primarily used on smartphones (yes, this is possible with a monolith)
An application that can be used to document decisions made during the development process of machines and systems and to perform risk assessments
A customer portal for inquiries

I am also working on a system for instant piping quotes that will be connected to Shopify.

While I relied almost entirely on Claude at the beginning to quickly produce code (which I still reviewed), I naturally became more and more involved with Rails over time.

In the process, I have also grown to appreciate and love Rails more and more.

What excites me is the open approach, and that is exactly what I still found lacking in ASP.NET Core, even though it is open source. What do I mean by an open approach?

When reading the ASP.NET documentation, there are repeated references to how to perform certain tasks with Visual Studio.

This distracts from the actual problem you want to solve and shows what Microsoft really wants to achieve: buy our tool.

When it comes to deployment, the "easy way" always points to Azure.

As already mentioned, Rails has no preference here: if you have a server running Docker, you can deploy with Kamal. End of story.

But even beyond that, it's always exciting to see that the people who maintain and develop Rails also use it to develop applications.

This is evident in many small details.

If you use includes, for example, you can see where an include begins and ends in the HTML code in the browser during development. This makes visual debugging much easier.

Another example is setting up a new project with Rails.

You can configure so many options - and it's easy to do using the Rails CLI: which type of database, the CSS framework and which parts not to scaffold at an insane level of granularity.

Another great feature is the Rails Console. You can easily interact with your application and database.

With Hotwire and Turbo, Rails offers an approach to integrating JavaScript into Rails applications.

With Turbo, it takes a similar approach to HTMX.

Everything is opt-in and lightweight.

Finally, I would like to circle back to the TL;DR at the beginning and briefly address the topic of performance comparison:

Ruby - and therefore Rails - is not the fastest platform on the planet.

But at the very least, a platform like Shopify has been running on it since the beginning, managing billions in sales for tens of thousands of companies.

So if I ever need to scale Rails to this extent with our company, which has fewer than 20 employees, I will gladly take on the challenge and still have fun doing it.

My tmux + Rails + AI TUIs development setup

2026-02-11T22:00:00Z

I've switched my tech stacks several times in the past 10+ years. Something that has been consistently there throughout these times has been tmux. Here's how I'm using it with Rails + AI TUIs.

So what's tmux?

tmux is a terminal multiplexer. It lets you switch easily between several programs in one terminal, detach them (they keep running in the background) and reattach them to a different terminal.

I became aware of tmux around 2014 when I switched from Windows to Linux and I sshed into my servers and connections sometimes have been interrupted.

This is one thing tmux gracefully handles for you: when an shh connection is interrupted, and gets re-established, the tmux-session you started on the remote is still there so you can just attach to it and continue where you left of. Doing Linux updates via ssh this way is also less risky.

But there's more to it.

When starting tmux in your terminal, you notice it running by the sticky info bar at the bottom of your terminal:

If you didn't set up anything in your ~/tmux.conf, you can just use the terminal as is.

Sometimes, you might want to have multiple terminals beneath each other and you can do that easily using tmux: Hit <leader>+<shift>+2 and the tmux window will split horizontally:

If you need a vertical split, use <leader>+<shift>+5>.

These splits can be nested arbitrarily:

What's the `<leader>`?

If you're familiar with tools like nvim, you already know, what a <leader> is and the default for tmux is C-b which means CTRL+b.

So <leader>+<shift>+2 means "Hit CTRL+b, followed by <SHIFT+2>".

I've sticked with this default leader key for more than 10 years but after reading this great book about LazyVim (more specifically Chapter 2) last year and some pain in the wrist, I noticed that the root cause might be using the default tmux leader key.

Long story short: a few weeks ago, I changed my leader leader key to LEFT-ALT-M and this is much more comfortable to me. I can hit the LEFT-ALT key with my left thumb and the M key with my right index finger instead of stretching my left hand for <CTRL+b>.

Split panes are great but how do I navigate?

So with all these nested panes around, how do you select a particular one?

<leader>-q is here for the rescue. This will bring up an overlay with the numbers of the panes. Hitting this number rigth after <leader>-q, will focus that pane:

If you want to get rid of a pane, just exit that particular terminal.

You've got more?

Let's consider you're building a web application and there's some development tooling required:

a web server
one or more database(s) in Docker container(s)
a editor, most likely nvim
a shell to execute commands like bin/rails or bin/kamal
one ore more AI agent TUIs, e.g. opencode
a database TUI like sqlit
a TUI to manage Docker like lazydocker

That's much more than you could fit into a few nested panes.

But tmux has got you covered: we can create new Windows inside tmux easily by hitting <leader>-c.

You can navigate them by using <leader>-<number-of-the-window>.

Having windows and panes at hand, you can now create and environment where your complete tooling is running side by side:

tmux app window

tmux layzvim window

tmux shell window

tmux opencode window

tmux sqlit window

The only downside: you have to re-create all of them after quitting the session.

If you keep running the session like forever, you can just detach from it using <leader>-d.

Using tmux ls you get a list of all running tmux sessions and you can attach to a running session using tmux attach -t <session-number>.

If you have multiple sessions running (I've almost 10 parallel tmux sessions running while writing this - in a tmux session, of course), identifying them by number, is not the easiest thing.

Hit <leader>-$ and give your session a memorable name.

Now you can also attach to it using tmux attach -t <session-name>.

Anyway, at some point you'll restart you machine and everything is gone...

Tmuxinator has entered the chat

That's where another tool comes handy: tmuxinator.

Tmuxinator helps you manage complex terminal sessions easily. Create, manage, and automate your dev environment with simple YAML configuration files today.

With tmuxinator you can persist your complex layouts in YAML files.

A YAML file for the session described above, could look like this:

name: name-of-session
root: path/to/the/project

windows:
  - dev:
      layout: even-vertical
      panes:
        - docker compose up -d
        - bin/dev
  - editor: nvim .
  - shell: bash
  - agent: opencode
  - sql: sqlit

This .tmuxinator.yml (notice the dot) file can be stored in multiple places: either in the root of your project or in the ~/.config/tmuxinator/ folder.

My workflow is to keep it inside the project and symlink it to the ~/.config/tmuxinator/ folder.

That way you can start a session from elsewhere globally using tmuxinator start <name-of-session>. If the session is already running, it will just attach to it.

If you enable bash completion for tmuxinator, you can just type tmuxinator start + <TAB> and it'll give you the list of defined sessions.

As tmuxinator is quite long to type, it is common, to alias it to mux (make sure to enable completion for this as well).

Speaking of running tmux session: you can easily hop between sessions using <leader>-s. This gives you a list of tmux sessions with a preview of it's windows and panes and you can just hit enter or the number of the session to switch to it:

With this at hand, you literally need just one instance of your Terminal.

And of course, you can always your mouse / trackpad if you enable it your tmux configuration.

Mine can be found here.

One more thing

tmux is comming to the Omarchy menu soon:

Introducing lazyqmd: a tui for QMD - and a little more...

2026-02-13T22:00:00Z

What's it all about?

QMD is a quite popular mini cli search engine for your docs, knowledge bases, meeting notes, whatever.

qmd has been created by Tobi Luetke, the founder of Shopify and can be found on GitHub.

It allows you to index Markdown files from several locations on your computer.

You can search with keywords or natural language.

QMD combines BM25 full-text search, vector semantic search, and LLM re-ranking—all running locally via node-llama-cpp with GGUF models.

After installing it, you can add a new collection like this:

qmd collection add ~/notes --name notes

Now all Markdown files under ~/notes will be indexed and be searched like this:

qmd search -c notes "search term"

If you have multiple collections, you can do a global search:

qmd search "search term"

You can query or do a vector search (see docs for more details).

qmd also provides a mcp server, so you can integrate it as a memory server into your agentic workflows:

qmd mcp --http

This will run start the mcp server on port 8181.

Of course you can specify another port and you can also run it in daemon mode:

qmd mcp --daemon --http --port 9000

So if I have a collection named blog which points to the source repository of my blog on my computer, I can run a search like this:

qmd search tmux

This will search all collections, hence also my collection named blog and the results will look like this:

qmd://blog/articles/my-tmux-tmuxinator-rails-ai-development-setup/index.md:2 #b9e642
Title: So what's tmux?
Score:  92%

@@ -1,4 @@ (0 before, 156 after)
---
title: "My tmux + Rails + AI TUIs development setup"
date: 2026-02-11T22:00:00
layout: default

Earlier today I was curious if I could display the whole Markdown file instead of result shown above and I came up with the idea of building a Temrinal UI (TUI) for for qmd - lazyqmd was born.

Introducing lazyqmd

As with qmd itself, lazyqmd can be installed using bun:

bun install -g lazyqmd

To use all of the lazyqmd features, make sure to start the qmd mcp server in daemon mode as shown before. If you stick with the default port, you're good to go.

If you set another port, you can configure lazyqmd to use this one in the ~/.config/lazyqmd/options.json file (for more details, take a look at the README).

Now we're ready to start lazyqmd:

lazyqmd

If you're starting from scratch without prior usage of qmd itself, you'll have no collections at hand and lazyqmd will look like this:

As can bee seen from the bottom bar in the screenshot, there's a command Add which can be invoked by pressing the a key - this brings up a little dialog to add a new collection:

Please notice, that you get tab completion for the path.

Please wait until the Indexing... message disappears. Once, the collection has been indexed, you can start using it. lazyqmd should look similar to this now:

You can navigte the collections in the left sidebar using up and down arrows and you can start a new search by either sticking with the All selection for a global search or you can select a particular collection and search this one.

Let's select blog and hit / to bring up the search dialog:

Now lets type "tmux":

Htting "Enter" will bring up the search results for this particular search term:

The first result seems interesting as it has a relevance of 86%. So lets hit <tab> to jump to the results list follow by Enter to open that particular document:

Now you can scroll inside this document and as can be seen, there's some syntax highlighting for Markdown and YAML frontmatter.

At this point I thought it would be nice to have a HTML preview at hand, so I've added it. Within the Markdown preview just hit <p>:

As expected, this brings up a Chrome, Chromium or Brave instance in app mode. If you're living the dream and run Omarchy, everything will be auto aligned nicely thanks to hyprland.

Now I wanted to go a little further: What if I could just edit the file and get a sort of hot reload of the HTML?

Lets focus the lazyqmd window and hit <e> for "Edit":

If your $EDITOR is nvim, this will seamlessly open the Markdown file in neovim.

Now lets make a little change to our Markdown file:

As you can see, when saving the change, the change is reflected in the HTML preview.

Quitting nvim will bring you back to lazyqmd where you left off.

Looking at the search screen again, you might have noticed, there's a "Mode" command show in the command bar at the bottom:

By hitting <CTRL+T> you can switch between regular search, vsearch (QMD Vector search) and query.

If you want to use vsearch, make sure you've created the Embeddings. If you didn't so far, you can just hit <e> on the main screen with a collection selected. This will run qmd ebmed for you and create the Embeddings.

After finishing this, I noticed that this little TUI + QMD might replace LogSeq and Obsidian for me: file based, run locally and I can have my files where they belong to- lets see how this works in daily use.

For more features, please have a look at the README on GitHub.

As this project is pretty new, expect not everything to be perfect right now.

Introducing zugpferd: XRechnung and ZUGFeRD e-invoicing for Ruby

2026-02-16T22:00:00Z

What's it all about?

If you're dealing with invoicing in Germany or Europe, chances are you've heard of XRechnung and ZUGFeRD. Starting January 2025, e-invoicing became mandatory for B2B transactions in Germany.

The European standard EN 16931 defines a semantic data model for electronic invoices and supports two XML syntaxes: UBL 2.1 and UN/CEFACT CII. XRechnung is the German compliance profile on top of EN 16931, while ZUGFeRD (also known as Factur-X in France) adds the ability to embed the structured XML data into a PDF/A-3 document - creating a hybrid invoice that is both human-readable and machine-processable.

Most existing libraries for this are written in Java or .NET. I wanted something that feels native to Ruby - plain Ruby objects, BigDecimal for monetary values, Date fields, and a clean API. That's why I built zugpferd.

Introducing zugpferd

zugpferd is a Ruby gem for reading, writing, and converting e-invoices according to EN 16931. It supports both UBL 2.1 and UN/CEFACT CII syntaxes, and optionally handles PDF/A-3 embedding and Schematron validation.

Features

UBL 2.1 & CII - Full support for both EN 16931 syntaxes: read, write, and roundtrip for any XRechnung or ZUGFeRD document
Multiple document types - Invoice, Credit Note, Corrected Invoice, Self-billed Invoice, Partial Invoice, and Prepayment Invoice
PDF/A-3 embedding - Create ZUGFeRD/Factur-X hybrid invoices by embedding XML into PDF/A-3 via Ghostscript
Validation - Validate invoices against EN 16931 and XRechnung business rules using Schematron (optional Java dependency)
Format conversion - Read CII, write UBL (or vice versa) through a format-agnostic data model
Pure Ruby data model - BigDecimal amounts, Date fields, simple Ruby objects mapped to EN 16931 Business Terms

Installation

Add it to your Gemfile:

gem "zugpferd"

Then:

bundle install

For PDF/A-3 embedding, you'll also need Ghostscript installed:

# Debian/Ubuntu
sudo apt-get install ghostscript

# Arch Linux
sudo pacman -S ghostscript

# macOS
brew install ghostscript

Document types

zugpferd supports all common EN 16931 document types, each with a dedicated model class:

Class	Type Code	Description
`Model::Invoice`	380	Commercial Invoice
`Model::CreditNote`	381	Credit Note
`Model::CorrectedInvoice`	384	Corrected Invoice
`Model::SelfBilledInvoice`	389	Self-billed Invoice
`Model::PartialInvoice`	326	Partial Invoice
`Model::PrepaymentInvoice`	386	Prepayment Invoice

All document types share the same attributes and work identically with both UBL and CII readers and writers:

credit_note = Zugpferd::Model::CreditNote.new(
  number: "CN-001",
  issue_date: Date.today,
  currency_code: "EUR"
)

corrected = Zugpferd::Model::CorrectedInvoice.new(
  number: "C-001",
  issue_date: Date.today
)

In UBL, a CreditNote produces a <CreditNote> root element while all other types produce <Invoice>. In CII, the structure is identical for all types - only the type code differs.

Building an invoice

Let's walk through creating an XRechnung-compliant invoice, validating it, and embedding it into a ZUGFeRD PDF.

First, require the necessary modules:

require "zugpferd"
require "zugpferd/pdf"
require "zugpferd/validation"
require "bigdecimal"

Setting up the invoice header

invoice = Zugpferd::Model::Invoice.new(
  number: "RE-2024-0042",
  issue_date: Date.new(2024, 6, 15),
  currency_code: "EUR"
)

invoice.due_date = Date.new(2024, 7, 15)
invoice.delivery_date = Date.new(2024, 6, 15)
invoice.buyer_reference = "LEITWEG-123-456"
invoice.customization_id = "urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0"
invoice.profile_id = "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0"

Adding seller and buyer

invoice.seller = Zugpferd::Model::TradeParty.new(name: "Zugpferd GmbH")
invoice.seller.vat_identifier = "DE123456789"
invoice.seller.electronic_address = "zugpferd@example.com"
invoice.seller.electronic_address_scheme = "EM"
invoice.seller.postal_address = Zugpferd::Model::PostalAddress.new(
  country_code: "DE",
  city_name: "Frankfurt am Main",
  postal_zone: "60311",
  street_name: "Kaiserstr. 42"
)
invoice.seller.contact = Zugpferd::Model::Contact.new(
  name: "Max Mustermann",
  telephone: "+49 69 12345678",
  email: "rechnung@zugpferd.example.com"
)

invoice.buyer = Zugpferd::Model::TradeParty.new(name: "Muster AG")
invoice.buyer.electronic_address = "muster@example.com"
invoice.buyer.electronic_address_scheme = "EM"
invoice.buyer.postal_address = Zugpferd::Model::PostalAddress.new(
  country_code: "DE",
  city_name: "Berlin",
  postal_zone: "10115",
  street_name: "Unter den Linden 1"
)

Adding line items

# Position 1: Software licenses
line1 = Zugpferd::Model::LineItem.new(
  id: "1",
  invoiced_quantity: "5",
  unit_code: "C62",
  line_extension_amount: "2500.00"
)
line1.item = Zugpferd::Model::Item.new(
  name: "Zugpferd Enterprise License",
  tax_category: "S",
  tax_percent: BigDecimal("19")
)
line1.price = Zugpferd::Model::Price.new(amount: "500.00")
invoice.line_items << line1

# Position 2: Consulting
line2 = Zugpferd::Model::LineItem.new(
  id: "2",
  invoiced_quantity: "16",
  unit_code: "HUR",
  line_extension_amount: "2400.00"
)
line2.item = Zugpferd::Model::Item.new(
  name: "Technische Beratung E-Invoicing",
  tax_category: "S",
  tax_percent: BigDecimal("19")
)
line2.price = Zugpferd::Model::Price.new(amount: "150.00")
invoice.line_items << line2

# Position 3: Workshop
line3 = Zugpferd::Model::LineItem.new(
  id: "3",
  invoiced_quantity: "1",
  unit_code: "C62",
  line_extension_amount: "1800.00"
)
line3.item = Zugpferd::Model::Item.new(
  name: "Workshop: XRechnung & ZUGFeRD in der Praxis (2 Tage)",
  tax_category: "S",
  tax_percent: BigDecimal("19")
)
line3.price = Zugpferd::Model::Price.new(amount: "1800.00")
invoice.line_items << line3

Tax, totals, and payment

netto = BigDecimal("6700.00")
steuer = BigDecimal("1273.00")
brutto = BigDecimal("7973.00")

invoice.tax_breakdown = Zugpferd::Model::TaxBreakdown.new(
  tax_amount: steuer.to_s("F"),
  currency_code: "EUR"
)
invoice.tax_breakdown.subtotals << Zugpferd::Model::TaxSubtotal.new(
  taxable_amount: netto.to_s("F"),
  tax_amount: steuer.to_s("F"),
  category_code: "S",
  currency_code: "EUR",
  percent: BigDecimal("19")
)

invoice.monetary_totals = Zugpferd::Model::MonetaryTotals.new(
  line_extension_amount: netto.to_s("F"),
  tax_exclusive_amount: netto.to_s("F"),
  tax_inclusive_amount: brutto.to_s("F"),
  payable_amount: brutto.to_s("F")
)

invoice.payment_instructions = Zugpferd::Model::PaymentInstructions.new(
  payment_means_code: "58",
  account_id: "DE89370400440532013000"
)

Writing XML

Now generate the CII XML:

xml = Zugpferd::CII::Writer.new.write(invoice)
File.write("invoice.xml", xml)

Need UBL instead? Just swap the writer:

xml = Zugpferd::UBL::Writer.new.write(invoice)

Format conversion

Since the data model is format-agnostic, converting between UBL and CII is straightforward:

# Read a CII invoice, write it as UBL
cii_xml = File.read("invoice_cii.xml")
invoice = Zugpferd::CII::Reader.new.read(cii_xml)
ubl_xml = Zugpferd::UBL::Writer.new.write(invoice)

Validation

Before sending an invoice, you probably want to make sure it's valid. zugpferd supports Schematron validation against EN 16931 and XRechnung business rules.

First, download the required schemas:

bin/setup-schemas

Then validate:

validator = Zugpferd::Validation::SchematronValidator.new(
  schemas_path: "vendor/schemas"
)
errors = validator.validate_all(xml, rule_sets: [:cen_cii, :xrechnung_cii])
fatals = errors.select { |e| e.flag == "fatal" }

if fatals.any?
  fatals.each { |e| puts "  [#{e.id}] #{e.text}" }
else
  puts "Invoice is valid."
end

Schematron validation requires Java and Saxon HE. If you don't need it, just skip the require "zugpferd/validation" - the core library works without Java.

PDF/A-3 embedding

This is where ZUGFeRD comes in: embedding the structured XML into a PDF, creating a hybrid document that works for both humans and machines.

embedder = Zugpferd::PDF::Embedder.new
embedder.embed(
  pdf_path: "invoice.pdf",
  xml: xml,
  output_path: "invoice_zugferd.pdf",
  version: "2p1",
  conformance_level: "XRECHNUNG"
)

The result is a PDF/A-3 compliant file with the XML attached as factur-x.xml. This works with ZUGFeRD 1.0, 2.0, and 2.1, and supports all conformance levels from MINIMUM to XRECHNUNG.

Reading invoices

Of course, zugpferd also reads existing invoices:

# UBL
xml = File.read("invoice.xml")
invoice = Zugpferd::UBL::Reader.new.read(xml)
puts invoice.number          # => "RE-2024-0042"
puts invoice.seller.name     # => "Zugpferd GmbH"
puts invoice.monetary_totals.payable_amount  # => 7973.0

# CII
invoice = Zugpferd::CII::Reader.new.read(cii_xml)

The reader auto-detects document types: Credit Notes, Corrected Invoices, and all other EN 16931 type codes are mapped to their respective model classes.

Wrapping up

zugpferd aims to make e-invoicing in Ruby feel natural - no XML wrangling, no Java dependencies for core functionality, just plain Ruby objects.

For the full documentation, check out the docs.

The source code is available on GitHub.

As this is a fairly new project, feedback and contributions are welcome.

Run Dropbox Headless as a Service Without User Session Login

2026-03-08T12:00:00Z

The Problem

Dropbox stops syncing when no user is logged in. On a headless server or a machine that isn't always attended, this means your files go stale whenever the session ends.

The Solution

Run Dropbox as a systemd user service with loginctl enable-linger. This keeps Dropbox running at boot — no active session required.

1. Create the service file

Place this at ~/.config/systemd/user/dropbox.service:

[Unit]
Description=Dropbox Sync Service
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=/home/YOUR_USER/.dropbox-dist/dropboxd
Environment=HOME=/home/YOUR_USER
Environment=DISPLAY=
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target

Replace YOUR_USER with your actual username.

2. Enable and start the service

systemctl --user enable dropbox.service
systemctl --user start dropbox.service

3. Enable linger

This is the key step — it tells systemd to start your user services at boot, even without an active login session:

sudo loginctl enable-linger YOUR_USER

4. Verify

systemctl --user status dropbox.service     # should show active (running)
loginctl show-user YOUR_USER | grep Linger  # should show Linger=yes

Important Note

Dropbox must be installed and linked to your account at least once in an interactive session before this setup works. Run dropboxd manually first, follow the authentication link, and then switch to the systemd service.

Introducing LazyDbx: a TUI for Dropbox

2026-03-12T12:00:00Z

What's it all about?

In my previous post, I showed how to run Dropbox as a systemd user service so it keeps syncing even when no user is logged in.

That setup works well — but it introduces a few new challenges:

The Dropbox desktop app might not start anymore. When Dropbox runs as a systemd service, the desktop app finds the already running daemon but fails to show a tray icon because the communication runs through the socket. This is a known issue with the headless service setup.
You might want to manage Dropbox from a terminal in general — not everyone runs a desktop environment, and even on desktop machines, a TUI can be faster than the Dropbox UI.
Over SSH, you need a way to check sync status, exclude folders, or add folders back — and the built-in dropbox CLI is limited. It can only show you files that are already synced locally. Excluded folders and their contents are completely invisible.

That last point is the real problem: once you exclude a folder from sync, the dropbox CLI has no way to show you what's on the server. You're flying blind.

Introducing LazyDbx

LazyDbx is a terminal UI (TUI) for Dropbox, built with OpenTUI and Bun.

It lets you browse your local and remote Dropbox files, manage sync exclusions, and create share links — all from the terminal.

Requirements

Bun v1+
Dropbox installed and running (either via dropbox start or as a systemd user service)
A Dropbox App for API access (optional, enables the Server tab)

Install

bun install -g github:alexzeitler/lazydbx

Or from source:

git clone https://github.com/alexzeitler/lazydbx.git
cd lazydbx
bun install

Setup

Each user creates their own Dropbox App. Credentials and tokens stay on your machine (~/.config/lazydbx/config.json) — all API requests go directly from your computer to Dropbox, no third-party servers involved.

1. Create a Dropbox App

Go to https://www.dropbox.com/developers/apps and create a new app:

Access type: Scoped access, Full Dropbox
Permissions tab: Enable account_info.read, files.metadata.read, and sharing.write. Then click Submit in the black overlay bar at the bottom.

2. Initialize config

lazydbx init

This prompts for your App Key and App Secret and saves them to ~/.config/lazydbx/config.json.

3. Authorize

lazydbx auth

This opens the Dropbox authorization URL. Copy the code from the Dropbox page and paste it into the terminal. Tokens are saved automatically.

To re-authorize (e.g. after changing scopes):

lazydbx auth --force

4. Run

lazydbx

Browsing your Dropbox

Local

Browse files and folders synced locally in ~/Dropbox. You can exclude folders from sync, create share links, copy links, and check the sync status of individual files.

Server

Browse the complete Dropbox folder structure via the API — including folders and files that have never been synced to this machine. This is the key difference to the built-in dropbox CLI: you can see everything on the server, not just what's local.

Without a configured Dropbox App, the Server tab falls back to the local filesystem combined with the exclude list.

Keybindings

Global

Key	Action
`Tab`	Switch between Local and Server
`r`	Refresh
`q`	Quit

Local tab

Key	Action
`j`/`k`	Navigate up/down
`Enter`	Open folder or file
`u`	Go up one directory
`e`	Exclude folder from sync
`s`	Get share link
`y`	Copy last share link
`f`	Show file sync status

Server tab

Key	Action
`j`/`k`	Navigate up/down
`Enter`	Open folder (or file if synced)
`u`	Go up one directory
`Space`	Toggle sync (exclude/include)
`a`	Show auth status

Early days

LazyDbx is a fresh project and might still have rough edges. If you run into issues or have ideas, feel free to open an issue or send a pull request on GitHub.

Introducing sshimg.nvim: Paste Images into Remote Neovim over SSH

2026-03-16T12:00:00Z

The problem

When you write Markdown locally, pasting images is trivial - plenty of Neovim plugins handle it. But when you're editing files on a remote server over SSH, your clipboard lives on a different machine than your editor. The remote Neovim has no access to your local clipboard, so none of those plugins work.

I ran into this while writing blog posts and documentation on remote machines. Taking a screenshot is easy, but getting that image from my local clipboard to the server and into the Markdown file required a manual workflow every time: save the screenshot locally, scp it over, then type the Markdown image link by hand.

How sshimg.nvim solves it

sshimg.nvim connects your local clipboard to your remote Neovim through a small daemon and an SSH reverse tunnel.

The flow looks like this:

Screenshot (local) → imgd daemon → SSH reverse tunnel → scp → Remote Neovim

You take a screenshot on your local machine (it lands in the clipboard).
You press <leader>pa or <leader>pp in Neovim.
The plugin contacts the local daemon through the SSH reverse tunnel.
The daemon reads the image from the clipboard, sends it to the server via scp.
Neovim inserts a Markdown image link at the cursor position.

The result:

![](assets/2026-03-15-23-25-25.png)

Setup

Local machine

1. Install the daemon

The daemon imgd is a small Python script that reads images from wl-paste (Wayland) and serves them over a local port.

cp daemon/imgd.py ~/.local/bin/imgd
chmod +x ~/.local/bin/imgd

2. Start the daemon

Start it as a systemd user service:

cp daemon/imgd.service ~/.config/systemd/user/imgd.service
systemctl --user enable --now imgd

Or run it manually:

imgd

3. Connect with a reverse tunnel

The reverse tunnel forwards port 9999 from the remote server back to your local machine, so the plugin can reach the daemon.

ssh -R 9999:localhost:9999 yourserver

Or add it to ~/.ssh/config so you don't have to type it every time:

Host yourserver
    RemoteForward 9999 localhost:9999

Remote server

Install the plugin with your package manager. For lazy.nvim:

return {
  "AlexZeitler/sshimg.nvim",
  config = function()
    require("sshimg").setup({
      port = 9999,
      host = "127.0.0.1",
      keymaps = {
        assets   = "<leader>pa",  -- Save to ./assets/
        parallel = "<leader>pp",  -- Save to same dir as current file
      },
    })
  end,
}

The values shown are the defaults - you only need to change them if your tunnel uses a different port.

Usage

Take a screenshot (it lands in your local clipboard).
Open a Markdown file in remote Neovim.
Press <leader>pa to save the image to ./assets/ or <leader>pp to save it next to the current file.

The plugin inserts the Markdown image link at your cursor position automatically.

Requirements

Local machine:

wl-paste (Wayland)
scp
Python 3

Remote server:

Neovim
Python 3

Early days

sshimg.nvim currently supports Linux with Wayland. Support for X11 and macOS is planned. If you run into issues or have ideas, feel free to open an issue or send a pull request on GitHub.

Paste clipboard images into Claude Code over SSH

2026-03-27T12:00:00Z

The problem

Claude Code is multimodal. It can read and reason about images using the Read tool. But when you run Claude Code on a remote server over SSH, there's no way to paste an image from your local clipboard into the session. The clipboard lives on your local machine, while Claude Code runs on the server.

I ran into the same issue with Neovim and built sshimg.nvim to solve it. Now I've built the same thing for Claude Code: claude-ssh-image-skill.

How it works

The solution has three parts:

ccimgd: a daemon running on your local machine that reads PNG images from the clipboard (wl-paste on Wayland, xclip on X11, pngpaste on macOS) and serves them as base64-encoded JSON over TCP on port 9998
ccimg: a client binary on the remote server that connects to the daemon, receives the image, and saves it as a temporary PNG file
/paste-image: a Claude Code skill that runs ccimg and then uses the Read tool to display the image to Claude

The connection between client and daemon runs through an SSH reverse tunnel:

Local Machine                            Remote Server (SSH)
┌──────────────────────┐                 ┌──────────────────────────┐
│  Clipboard (PNG)     │                 │  Claude Code             │
│        │             │                 │        │                 │
│        ▼             │                 │        ▼                 │
│  ccimgd (Port 9998)  │◄────────────────│  /paste-image Skill      │
│  - wl-paste          │  SSH Reverse    │  - TCP Request to ccimgd │
│  - Returns base64    │  Tunnel         │  - Receives base64 image │
│    image in response │  (Port 9998)    │  - Saves as temp file    │
│                      │                 │  - Read → Claude sees    │
└──────────────────────┘                 │    the image             │
                                         └──────────────────────────┘

Building

Both binaries are written in Go and compile as fully static binaries with no runtime dependencies:

git clone https://github.com/AlexZeitler/claude-ssh-image-skill.git
cd claude-ssh-image-skill
./build.sh

This builds statically linked binaries for all supported platforms:

daemon/ccimgd-linux-amd64, daemon/ccimgd-darwin-amd64, daemon/ccimgd-darwin-arm64
client/ccimg-linux-amd64, client/ccimg-darwin-amd64, client/ccimg-darwin-arm64

Setup

Local machine (Linux)

cp daemon/ccimgd-linux-amd64 ~/.local/bin/ccimgd
cp daemon/ccimgd.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now ccimgd

Local machine (macOS)

Requires pngpaste for clipboard access:

brew install pngpaste
cp daemon/ccimgd-darwin-arm64 /usr/local/bin/ccimgd   # or ccimgd-darwin-amd64 for Intel
cp daemon/com.ccimgd.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/com.ccimgd.plist

Remote server

Copy the client binary and the Claude Code skill:

scp client/ccimg-linux-amd64 your-server:~/.local/bin/ccimg
scp skill/paste-image.md your-server:~/.claude/commands/paste-image.md

To skip permission prompts, add the Bash permission to ~/.claude/settings.json on the server:

{
  "permissions": {
    "allow": [
      "Bash(ccimg)"
    ]
  }
}

SSH connection

Connect with a reverse tunnel so the remote ccimg can reach the local ccimgd:

ssh -R 9998:localhost:9998 your-server

Or add it permanently to ~/.ssh/config:

Host your-server
    RemoteForward 9998 localhost:9998

Usage

Copy an image to the clipboard on your local machine, then run this in Claude Code on the remote server:

/paste-image

Claude receives the image and can reason about it: screenshots, diagrams, error messages, whatever you need.

The skill

The skill itself is minimal. It's a Markdown file that tells Claude what to do:

Paste an image from the local clipboard into this session.

Instructions:
1. Run `ccimg` using the Bash tool.
2. Use the Read tool to read the printed file path.
   This will display the image to Claude.

Claude Code skills are just natural language instructions stored in ~/.claude/commands/. When you invoke /paste-image, Claude follows the instructions: run the client, get the file path, read the image.

The daemon

ccimgd listens on 127.0.0.1:9998 and waits for a TCP connection. When a client connects and sends a newline-terminated message, the daemon reads the clipboard image and responds with a JSON object:

type response struct {
    OK    bool   `json:"ok"`
    Image string `json:"image,omitempty"`
    Error string `json:"error,omitempty"`
}

The Image field contains the base64-encoded PNG data. The daemon auto-detects the platform and uses wl-paste on Wayland, xclip on X11, or pngpaste on macOS.

The client

ccimg connects to 127.0.0.1:9998 (which the SSH reverse tunnel forwards to the local machine), sends {}\n, receives the JSON response, decodes the base64 image, writes it to a temp file, and prints the path to stdout. That's all Claude Code needs to pick it up with Read.

Coexistence with sshimg.nvim

If you also use sshimg.nvim, both tools can run simultaneously. imgd uses port 9999 while ccimgd uses port 9998.

Source

The full source is on GitHub: AlexZeitler/claude-ssh-image-skill

Introducing Aceto - a local dev server for building HTML mockups with AI

2026-04-01T12:00:00Z

The idea

Building HTML mockups with AI agents works surprisingly well - until you need to tell the agent which element to change. Describing "the second card in the pricing section" in plain text wastes tokens and is error-prone. Copying the full HTML back and forth is even worse.

Aceto takes a different approach: you point at an element in the browser, the agent gets a precise CSS selector. No pasting HTML, no guessing.

How it works

Aceto is not a drawing tool or visual editor. It is a feedback loop:

Tell the agent what you want
The agent generates or modifies real HTML + Tailwind CSS
See the result live in your browser
Point at an element and say "change this"
The agent understands which element you mean and modifies it

The agent connects via MCP (Model Context Protocol), so it works with Claude Code out of the box. The browser overlay provides the visual layer - hover highlighting, element selection, and inline editing - while the agent handles all structural changes through standard HTML manipulation.

Browser overlay

When you move the mouse over any element, a blue outline appears with the element's tag and classes:

Clicking an element selects it with a pink outline. The breadcrumb bar at the bottom shows the full DOM path. The scroll wheel navigates up and down the tree - parent and child elements:

The agent can also highlight elements in cyan to communicate visually - for example to ask "Do you mean this one?":

Both selections - pink for the user, cyan for the agent - can be visible at the same time.

Inline editing

Double-clicking any editable element lets you modify it directly in the browser. Text elements like headings and paragraphs open for text editing, inputs let you change their value, and checkboxes toggle on double-click:

Pressing c on a selected element opens an inline editor for its Tailwind classes:

Tables get special treatment - selecting a table cell shows a floating toolbar with controls for adding and removing rows and columns:

Token efficiency

This is where Aceto differs from other AI-driven UI tools. The agent does not need to read and parse the full HTML to understand what you mean. You point at an element in the browser, the agent gets a precise selector. Write tools use the current selection by default - one tool call, no roundtrip.

Component libraries

Aceto supports adding component libraries via the CLI. DaisyUI works out of the box with Tailwind v4:

aceto add daisyui

More features

Yank and paste - press y to copy a selected element, p to paste it after another selection
Paste images - Ctrl+V with a selection inserts an image instantly; without selection, it stages the image for agent-driven placement
Asset picker - press a to browse and reuse previously pasted images
Slash commands - type /list in an empty element to create lists
Content shortcuts - type [] or [x] in a cell to insert a checkbox
Element defaults - define default Tailwind classes for generated elements via aceto.defaults.json
Screenshots - the agent captures full-page or element-level screenshots via get_screenshot()
Live reload - DOM morphing keeps scroll position and selection state without page reload flicker

Getting started

Aceto requires Bun:

bun install -g github:alexzeitler/aceto

Create a new project and start the dev server:

mkdir my-mockup && cd my-mockup
aceto init
aceto dev

Then add it as an MCP server to Claude Code:

claude mcp add aceto -s user --transport http http://localhost:3000/mcp

That is all you need. Tell the agent what you want, point at elements to refine, and iterate until the mockup looks right.

What Aceto does not do

No build system - the output is a plain HTML file you can read with cat
No framework - Tailwind v4 via CDN, optionally DaisyUI or Flowbite
No abstraction layer - real HTML, no component model

The source code is on GitHub.

Rails Diff MCP - an MCP server for Rails version diffs

2026-04-01T18:00:00Z

The problem

Upgrading a Rails app from one version to the next means figuring out what changed in the default rails new output. You end up tabbing between RailsDiff in the browser, copying file names, and pasting diffs back into your editor. If you are using an AI agent to help with the upgrade, it cannot access that information on its own - you become the middleman.

What Rails Diff MCP does

Rails Diff MCP is an MCP server that gives your AI agent direct access to Rails version diffs. The data comes from the railsdiff/rails-new-output repository, where each Rails version is tagged with the output of rails new.

The server exposes three tools:

Tool	Description
`list_rails_versions`	List all available Rails versions (sorted)
`compare_rails_versions`	Compare two versions - returns a list of changed files
`get_file_diff`	Get the patch for a specific file between two versions

Instead of looking up diffs yourself, you tell the agent "upgrade this app from 8.0.1 to 8.0.2" and it can inspect every changed file on its own.

Setup

The server runs via Docker Compose:

docker compose up -d

It listens on http://localhost:8080/mcp with a health check at http://localhost:8080/healthz.

claude mcp add --transport http rails-diff http://localhost:8080/mcp

Optionally set a GITHUB_TOKEN environment variable to avoid GitHub API rate limits.

How an upgrade workflow looks

Once the MCP server is running and registered, a Rails upgrade conversation might go like this:

Ask the agent to compare your current Rails version with the target version
The agent calls compare_rails_versions and gets the list of changed files
For each relevant file, it calls get_file_diff to see the exact patch
It applies the changes to your project, adapting them to your existing configuration

No browser tabs, no copy-pasting diffs, no back-and-forth.

Credits

Built on top of RailsDiff by Andy Stewart and contributors.

The source code is on GitHub.

Setting up Chrome DevTools MCP with Claude Code on Linux (Wayland)

2026-04-01T19:00:00Z

If you are using Claude Code and want it to interact with a real browser - navigating pages, taking screenshots, clicking elements - the Chrome DevTools MCP server is the way to go.

On Linux with Wayland, getting this to work requires a few extra steps. Here is what I learned.

The problem

The Chrome DevTools MCP server uses Puppeteer under the hood. When you add it to your Claude Code config in ~/.claude.json like this:

{
  "mcpServers": {
    "chrome-devtools-npx": {
      "type": "stdio",
      "command": "npx",
      "args": ["chrome-devtools-mcp@latest"],
      "env": {}
    }
  }
}

...and try to use it, you will get an error like:

Missing X server to start the headful browser.
Either set headless to true or use xvfb-run to run your Puppeteer script.

This happens because Puppeteer tries to launch Chrome with X11, but your system is running Wayland.

First attempt: connecting to a running Chrome instance

One approach is to start Chrome yourself with remote debugging enabled and then point the MCP server at it:

google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug-profile --ozone-platform=wayland

Then configure the MCP server to connect to it:

{
  "chrome-devtools-npx": {
    "type": "stdio",
    "command": "npx",
    "args": ["chrome-devtools-mcp@latest"],
    "env": {
      "CHROME_CDP_URL": "http://localhost:9222"
    }
  }
}

This works, but you have to manually start Chrome with the right flags every time before using the MCP tools. Not great.

The solution: let the MCP server launch Chrome with the right flags

The chrome-devtools-mcp CLI supports --chromeArg flags that get passed through to Chrome when the MCP server launches it. This means we can tell it to use Wayland - and suppress the annoying first-run dialogs at the same time.

Here is the final config in ~/.claude.json:

{
  "mcpServers": {
    "chrome-devtools-npx": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "chrome-devtools-mcp@latest",
        "--chromeArg=--ozone-platform=wayland",
        "--chromeArg=--no-first-run",
        "--chromeArg=--no-default-browser-check",
        "--chromeArg=--disable-search-engine-choice-screen",
        "--no-usage-statistics",
        "--isolated"
      ],
      "env": {}
    }
  }
}

Let me break down the flags:

--chromeArg=--ozone-platform=wayland - tells Chrome to use the Wayland backend instead of X11
--chromeArg=--no-first-run - skips the "Welcome to Chrome" dialog
--chromeArg=--no-default-browser-check - skips the "Set as default browser?" prompt
--chromeArg=--disable-search-engine-choice-screen - skips the search engine selection screen
--no-usage-statistics - disables Google's usage statistics collection in the MCP server
--isolated - uses a temporary profile directory that gets cleaned up when Chrome closes

The --isolated flag is important: without it, the MCP server stores its Chrome profile in ~/.cache/chrome-devtools-mcp/chrome-profile/. If a previous Chrome instance is still running (or was not shut down cleanly), launching a new one will fail with "The browser is already running" because two Chrome instances cannot share the same profile directory. With --isolated, each session gets its own temporary profile, avoiding this conflict entirely.

With this configuration, Claude Code will automatically launch a Chrome window when it needs browser access. No manual Chrome start required.

Using it

After restarting Claude Code, you can use the Chrome DevTools tools right away. Claude can navigate to URLs, take screenshots, click elements, fill forms, inspect network requests, and more - all through the MCP tools.

Available CLI flags

The chrome-devtools-mcp CLI has quite a few options worth knowing about:

npx chrome-devtools-mcp@latest --help

Some useful ones:

--headless - run Chrome without a visible window
--viewport 1280x720 - set the initial viewport size
--slim - only expose 3 tools (navigation, JavaScript execution, screenshot) instead of the full set
--browserUrl http://127.0.0.1:9222 - connect to an already running Chrome instance
--isolated - use a temporary profile that gets cleaned up when Chrome closes
--channel canary - use Chrome Canary instead of stable

Wrapping up

The key insight is that the Chrome DevTools MCP server can launch Chrome on its own - you just need to pass the right platform flags via --chromeArg. On Wayland, that means --ozone-platform=wayland. Once configured, it just works.

waybar-worldclock - a simple world clock for Waybar

2026-04-03T18:00:00Z

If you use Waybar on your Linux desktop (for example with Omarchy), you might want to see the time in different timezones without opening a browser or running extra apps.

waybar-worldclock is a small utility that shows your local time in the bar and displays world times in the tooltip when you hover over it.

Installation

git clone https://github.com/alexzeitler/waybar-worldclock.git
cd waybar-worldclock
./install

This copies the worldclock script to ~/.local/bin/ and creates a default config at ~/.config/worldclock/zones if none exists.

Configuring timezones

Edit ~/.config/worldclock/zones with one timezone per line, tab-separated:

America/New_York    New York
Asia/Tokyo          Tokyo
Europe/London       London
Australia/Sydney    Sydney

You can find valid timezone names with timedatectl list-timezones.

Waybar setup

Replace the built-in clock module (or add alongside it) in your ~/.config/waybar/config.jsonc:

"modules-center": ["custom/worldclock"]

Then add the module definition:

"custom/worldclock": {
  "exec": "worldclock",
  "return-type": "json",
  "interval": 30
}

Restart Waybar (killall waybar && waybar &) and you are good to go.

Uninstall

./uninstall

The source code is on GitHub.

Alexander Zeitler

Farewell...

... .NET only software development

... blog.alexonasp.net

... BlogEngine.NET

MongoDB development environment journal size management using mongoctl

mongoose: Referencing schema in properties or arrays

#NodeJS / #ExpressJS: Adding routes dynamically at runtime

Stop complaining or improve yourself

Running ASP.NET 5 Beta 4 in Docker with DNX runtime #aspnet5 #docker

Update [2015-05-02]

Update [2015-05-01]

Update [2015-05-01]

Update [2015-05-02]

lowerCamelCase JSON with ASP.NET MVC 6

Deploying a ASP.NET MVC 6 API as Azure API App in Azure App Services

Setting some context...

First things first, the ASP.NET MVC 6 API

Creating the Swagger API definition file

Adding Azure API Apps Metadata

Publishing the API App

Integration-testing ASP.NET 5 / MVC 6 Controllers on DNX Beta 4

A lap around AWS and docker-machine

Docker Machine: NS_ERROR_FAILURE Failed to create the host-only adapter

Rename Visual Studio project including files, folders and namespaces

Chrome crashes on Ubuntu in VMware Workstation

Workflows: using Docker Machine and Docker Compose together in development

Plain Docker development workflow with Node.js / Express

Plain Docker workflow with Node.js and MongoDb

Simplifying container linking using Docker Compose

Adding Docker Machine to the scene

Docker Machine and Volumes

Docker Machine and Docker Compose together

Update 2016, 3rd February: One more thing... Docker networking

Resizing a VMware Workstation VM partition using GParted - get the swap partition out of my way!

Some thoughts on Open Source Software

Debugging Node.js + TypeScript in a Docker Container with WebStorm

Getting all registered routes in express.js

Deploying a private, secured Docker Registry within 15 minutes

Debugging a ES6 Node.js application in a Docker container using Visual Studio Code

Debugging mocha tests with Visual Studio Code when Node.js is installed using nvm

Debugging mocha tests in a Docker container using Visual Studio Code

Deploying Ubuntu Mate Desktop as a developer environment in AWS EC2

Running software in the Mate environment

Ubuntu Software Center

Changing the timezone

Dropbox

Restart / Shutdown via Mate

Docker on /mnt

Visual Studio Code

Deploying Ubuntu Mate Desktop as a developer environment in a Azure VM

Running software in the Mate environment

Ubuntu Software Center

Changing the timezone

Dropbox

Restart / Shutdown via Mate

Visual Studio Code / ATOM

Mongoose toObject and toJSON transform behavior with sub-documents

Non-Interactive Azure Resource Manager (ARM) login

Fixing Chrome 58+ [missing_subjectAltName] with openssl when using self signed certificates

Accessing an HTTP API running on your MacBook in a Docker container from your iPhone/iPad using dnsmasq

Getting started with CQRS

Running ASP.NET Core on minikube

Installing minikube

On macOS

On Linux (Ubuntu 18.04 here)

Installing kubectl

On macOS

On Linux (Ubuntu 18.04 here)

Running minikube

Dockerizing ASP.NET Core

Hello k8s

Accessing the Application using a Service

Passing a ViewModel by Attribute to ASP.NET Core ViewComponents

Enabling the Kubernetes Dashboard for DigitalOcean Kubernetes

Push vs. Pull - regaining control over time

Refresh ASP.NET Core MVC view without reloading the application

Parsing JSON parameters stored in AWS Parameter Store using jq

Hot reload tailwindcss changes with browser-sync

Initial setup

Docker on `/mnt`