Guides

Guides for how to do little things

Using wkhtmltopdf with Docker

Recently I needed to get wkhtmltopdf working in a Docker container with ASP.NET Core. The wonderful thing about Docker containers is that all dependencies are packaged up so you don’t have to worry about installs, versions, deployments, etc. But it does mean setting up the initial environment is a little trickier.

TL:DR Gimme the Dockerfile

For the impatient the full Dockerfile is as follows:

FROM microsoft/aspnetcore:1.1.2

COPY lib/wkhtmltox /usrtmp
RUN (cd /usrtmp && tar c .) | (cd /usr && tar xf -) && \
    chmod 555 /usr/bin/wkhtmltopdf && \
    apt-get update && \
    apt-get install -y --no-install-recommends zlib1g fontconfig libfreetype6 libx11-6 libxext6 libxrender1 && \
    rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY bin/Release/PublishOutput .
ENTRYPOINT ["dotnet", "Site.dll"]

Version Issues

You need to run a new enough version to operate correctly in headless mode on newer versions of Linux. 0.12.1-2 is the current version used by Debian, and this will not work. I used the latest 0.12.4 from the main site. Older versions also have heavy dependencies on X11, severely bloating your container.

The default package available in apt will not work.

Permissions Issues

By default, copying files into the Docker container will result in them being read-only, no execute permissions. Additionally, you can’t just do a RUN chmod and expect the files to have the updated permissions. This is due to a bug (maybe?) where you can’t really amend the permissions of another layer – it just doesn’t work. Instead you need to copy the files to one place, then apply your chmod changes:

COPY lib/wkhtmltox /usrtmp
RUN (cd /usrtmp && tar c .) | (cd /usr && tar xf -) && \
    chmod 555 /usr/bin/wkhtmltopdf

This copies the binaries from lib/wkhtmltox to the /usrtmp directory in the image, then moves the files to the real location of /usr. Finally, we set execute permissions for the binary itself.

Dependency Issues

Finally, wkhtmltopdf requires certain dependencies to be present to function. These can be installed as usual via apt:

RUN (apt-get update && \
    apt-get install -y --no-install-recommends zlib1g fontconfig libfreetype6 libx11-6 libxext6 libxrender1 && \
    rm -rf /var/lib/apt/lists/*

We have a few extra options here above what you’d normally run on your own personal Linux install:

–no-install-recommends

We only want the libraries we absolutely must have to make the tool work. So, this flag ensures only the minimum is installed, and not any extra utility packages that might be useful in a full-install. Remember this is a container, so the bare minimum is all we’ll ever need.

rm -rf /var/lib/apt/lists/*

Once we’ve got all the packages installed, we won’t be using the package cache again. So, remove it to keep the container size down.

Posted by Dan in Guides, Programming, 1 comment

Building an ASP.NET Core Docker Image on Linux

ASP.NET Core is super awesome, especially since it plays really well with the latest deployment methods. Microsoft has even gone as far as to pre-package an optimised .NET Core Docker image with the core libraries pre-compiled for a super-fast startup. So let’s get started, but first you’ll need to install Docker and the .NET Tools on your Linux machine if you haven’t already.

Add a Dockerfile

Add a new text file called ‘Dockerfile’ (case sensitive) to the root of your project, make sure it doesn’t have any extension (such as .txt). In the Dockerfile add the following code:

FROM microsoft/aspnetcore:1.1.0
WORKDIR /app
COPY ./output .
ENTRYPOINT ["dotnet", "MySite.dll"]

Update the ‘MySite.dll’ reference to the name of your project with a .dll extension. Also while you’re at it, change the version number of .NET Core if you’re not using 1.1 like I am. I highly recommend 1.1 or later with Linux due to much better performance.

Build from command line

Run the following commands in the project directory:

dotnet restore
dotnet publish -o output -c release

This will get all dependencies, compile a release build, and put the result into the ‘output’ directory. The reason we’re using a sub-directory is due to a bug in the tooling, if we use a parent relative path (../) the ‘publishOptions/include’ config setting in project.json will be ignored and you’ll be missing a chunk of your project!

Build the docker image

Now let’s get that code into a Docker image! Run the following command:

sudo docker build -t myapp .

Feel free to rename myapp to something a little more descriptive. You can also specify multiple tags, such as:

sudo docker build -t myapp -t myapp:1.0 .

It’s really up to you with regards to tagging. If you’re publishing to a repository (likely), make sure to add the applicable repository tag to the list.

Running the image

Run the following command to start up a new container:

sudo docker run -p 8000:80 myapp 

Make sure to update myapp to the name you used earlier when building. Your site should now be accessible on port 8000: http://localhost:8000

You may be wondering why we forwarded to port 80, and not 5000 or whatever port you’ve specified in launchSettings.json. As part of the aspnetcore image, an environment variable is set to tell Kestrel to host on port 80. This can be overridden either in your Dockerfile, or using app.UseUrl in your Program.cs file.

Don’t connect directly to the container

Remember, the site is still running in Kestrel so it’s not magically secure by virtue of running in a container. Make sure to use a reverse-proxy such as nginx when running your site in a production environment. Microsoft are working on hardening Kestrel so that you can use it directly in the future – but we’re not there yet.

Possible errors

Did you mean to run dotnet SDK commands?

You might get the following error upon execution:

Did you mean to run dotnet SDK commands? Please install dotnet SDK from:
http://go.microsoft.com/fwlink/?LinkID=798306&clcid=0x409

This basically means the .dll you referenced couldn’t be found. Double-check all of your paths and filenames. It’s easy to include the source instead of the output, or even save to / from the wrong directory.

Could not load <dependency>.dll

If you get dependency errors on execution, it means the output of the publish wasn’t saved to the /app folder within the container. The .dll files from the publish operation must all go directly into the root of the /app folder in the container. This means you can’t rename /app to something else.

More information

You can get more information from:

Github

Official MS Github: https://github.com/aspnet/aspnet-docker. Navigate to the version of .NET Core you want (1.0/jessie, 1.1/jessie, etc.). If you’re using the output of a publish, you’ll want the ‘runtime’ subfolder.

Docket

Official MS Docker Hub: https://hub.docker.com/r/microsoft/aspnetcore/. A quick overview of the base image, although it looks like MS want to spend most of their focus on the Github account.

Posted by Dan in Guides, 0 comments

‘env: node: No such file or directory’ Error in IntelliJ IDEA File Watcher

I was getting the following error when using the File Watcher feature in IntelliJ Idea to compile Typescript files:

/usr/local/bin/tsc –verbose –sourcemap test.ts
env: node: No such file or directory

The solution is relatively simple, you need to manually set the PATH environment variable in the File Watcher like so:

PATH variable in Idea File Watcher

 

You can get your environment’s PATH variable from ~/.MacOSX/environment.plist if you’re rocking a Mac. Alternatively you can probably use this one (again for a Mac):

/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin:/usr/X11/bin:/opt/local/bin

Posted by Dan in Guides, Mac, 8 comments

CIFilters with MonoMac

In a recent project I found I needed to colourise (colorize to you Americans!) a greyscale image. Fortunately Apple have built-in support for various colour filters, including the multiply filter I needed. Unfortunately CoreImage only works on CoreImage images, not NSImages – and there’s no easy way to convert between the two.

Original ImageRed TintGreen TintBlue Tint

Converting from CIImage to NSImage

Fortunately with Extension Methods, converting a CIImage to an NSImage isn’t too hard:

public static NSImage ToNSImage(this CIImage image)
{
	return ToNSImage(image, image.Extent.Size);
}

public static NSImage ToNSImage(this CIImage image, SizeF size)
{
	var imageRep = NSCIImageRep.FromCIImage(image);
	var nsImage = new NSImage(size);
	nsImage.AddRepresentation(imageRep);

	return nsImage;
}

First we get an NSCIImageRep instance from the CIImage – NSCIImageRep is a class that can render a CIImage. Next we create our new NSImage and use the AddRepresentation method to populate the NSImage with the CIImage. Internally the NSCIImageRep instance will render the CIImage to memory in a bitmap format, NSImage will then populate itself with this bitmap.

Tinting the Greyscale image with CoreImage

Now we don’t need to worry about using CIImages with abandon we can focus on the actual tinting. We need to load in our image, then we need to create a tint image, finally we need to multiply the two together just like in Photoshop. Let’s load in our graphics first:

var mainImage = CIImage.FromUrl(NSUrl.FromFilename(NSBundle.MainBundle.PathForResource(
	Path.GetFileNameWithoutExtension(ImagePath), Path.GetExtension(ImagePath))));
var tintImage = CIImage.ImageWithColor(CIColor.FromRgb(1f, 0f, 0f));

We load in the image using FromUrl here since it’s the most efficient manner. If we loaded in via an NSImage, we would be wasting memory in both the load and conversion process – better to load from the file system directly. If you need to use the same image repeatedly, load in the image as a byte array and create an instance of CIImage using the data.  Next we create our filter:

var filter = CIFilter.FromName("CIMultiplyCompositing");

Unfortunately MonoMac doesn’t contain strongly typed bindings for any CoreImage filters, so we need to populate the input parameters using Key-Value Coding:

filter.SetValueForKey(tintImage, (NSString)"inputImage");
filter.SetValueForKey(mainImage, (NSString)"inputBackgroundImage");

We need to cast here because Key-Value coding requires NSString instances. NSString has an implicit conversion operator for string, allowing us to cast string directly to NSString. Note the key names, these must match exactly, each filter has different parameters – a reference for all filter types and their parameters is available here. Now we can perform the tint and display the result:

var processedImage = (CIImage)filter.ValueForKey((NSString)"outputImage");
var outputImage = processedImage.ToNSImage();

ImageView.Image = outputImage;

And that’s it! If the filter fails for any reason ValueForKey will return NULL. The code above will apply a red tint and you should get something like:

Red Tint

Posted by Dan in C#, Guides, Mac, Mac, 0 comments

Getting Forward / Backward mouse buttons working in Parallels Desktop For Mac

This is a follow-on post from my earlier blog post ‘Getting Back / Forward mouse buttons working in Mac OS X‘.

The big problem now is getting forward / backward working in Parallels (and VMware Fusion if it doesn’t work on that either). The reason for the problem is that Parallels emulates the mouse so you can easily move the mouse into and out of the VM window. Additionally the emulator lets you use gestures from the touch pad in Windows (very cool). The problem is, the emulator doesn’t support more than 3 buttons.

The Easy Fix

The easiest fix is to turn off SmartMouse:

This will give Windows direct access to the mouse, and you’ll be able to use the MS driver directly. Unfortunately if you do this, you’ll have to give / take the mouse from the VM manually using CMD+OPT.

The Real Fix

The real fix is to use my favourite HID tool – ControllerMate. I won’t go over how to configure rules that only apply to VMs, etc. that’s all covered in my previous blog post. Instead, let’s jump right to the rule itself:

Drag on mouse buttons #4 and #5 as inputs, and then link them up to keystrokes building blocks. For the back building block you need to use ALT + Left Arrow, and for the forward block you need ALT + Right arrow, like so:

Once set up, back & forward will be fully functional in Windows programs that support the keyboard shortcut.

Make sure these rules are only executed for the VM – these shortcuts won’t work for Mac!

Posted by Dan in Guides, Mac, 1 comment

Reachability in MonoTouch

If you’re making an app that communicates with the network, at some point you’re going to need to check if the network is even there. This is where you need to use the NetworkReachability class, but it’s not particularly user-friendly. Tony Million produced a nice wrapper class, however it’s written in Obj-C not C#. Wouldn’t it be nice if there was a version in C# MonoTouch? Well now there is!

The Code & Usage

You can download the code at github here. Usage is really simple:

private Reachability _reachability;

public override void ViewDidLoad()
{
    base.ViewDidLoad();

    _reachability = new Reachability("www.google.co.uk");
    _reachability.ReachabilityUpdated += HandleReachabilityUpdated;
}

protected virtual void HandleReachabilityUpdated(object sender, ReachabilityEventArgs e)
{
    UpdateStatusLabel(e.Status, StatusLabel);
}

protected virtual void UpdateStatusLabel(ReachabilityStatus status, UILabel label)
{
    switch (status)
    {
        case ReachabilityStatus.NotReachable:
            label.Text = "Not Reachable";
            break;

        case ReachabilityStatus.ViaWiFi:
            label.Text = "Via WiFi";
            break;

        case ReachabilityStatus.ViaWWAN:
            label.Text = "Via WWAN";
            break;

        default:
            label.Text = "Unexpected status";
            break;
    }
}

Overview

To use, you create an instance of Reachability, specifying the remote host (or IP address) you need to connect to. Alternatively there are two static method that construct special versions of Reachability: ReachabilityForInternet, ReachabilityForLocalWiFi. These return an instance of Reachability that will be populated almost immediately, for this reason you need to use the CurrentStatus property of the instance, rather than relying on the update event. The update event will fire before you even have a chance to hook it up.

The ReachabilityUpdated event is fired whenever the connectivity changes. It’s highly recommended you use this event to track the connection, with mobile devices the connectivity can change at any time.

Caveats

There’s currently a bug in MonoTouch that causes the simulator to freeze when reachability is queried. The code will work fine on a device. Versions of MonoTouch designed for iOS 6 have fixed this bug, so if you’re using an iOS 6 capable version of MonoTouch you’ll be in the clear.

MonoMac

The code is designed to work with MonoMac too, however the SCNetworkReachability functions haven’t been bound yet. When they do I’ll update the code to work with MonoMac as well.

Posted by Dan in C#, Guides, MonoTouch, 1 comment

iPhone Glyphs from ‘Apple Symbols’ in Lion / Mountain Lion

The Apple Symbols font provides a lot of the symbols used in iOS, however since Lion it’s been harder to get at them. Here is how to use them if you’re on Lion or above:

First open Font Book and open up the Apple Symbols font.

Next, bring up the print dialog (CMD + P).

Now click on ‘Show Details’

Change the Report Type to ‘Repetoire’. Next change the glyph size to something larger, I find 30pt about right most of the time.

Now click on the PDF button in the bottom left, and save the PDF somewhere.

Next, start up Photoshop and drag the PDF into the stage.

You want the last couple of pages for the iOS glyphs. Make sure the resolution is high enough, I like to go for a dpi of 300. Click on OK and you should be presented with the glyphs nicely anti-aliased with a transparent background:

Glyps are ready to go!

Posted by Dan in Guides, iOS, Programming, Tutorials, 0 comments

Running multiple instances of MonoDevelop on Mac

By default OS X will only let you run a single instance of any app, which is OK if the app is designed with multiple windows & a single instance in mind. MonoDevelop is a different beast, and sooner or later you’re going to want to run at least 2 instances of it, here’s how:

First run the AppleScript editor, and enter the following code:

do shell script "open -n /Applications/MonoDevelop.app/"

Now save the script somewhere easily accessible, make sure to set the ‘File Format’ to ‘Application’. I chose the name ‘MonoDevelop Launcher’:

Now the only problem left is the icon, it’s most likely the AppleScript icon, rather than the MonoDevelop one:

Use ‘Get Info’ to get the info for both your new launcher, and MonoDevelop. Click on the icon for MonoDevelop and press CMD+C. Now click on the icon for your script, and press CMD+V. The icon should now be correct:

References: Based on answer by ‘Subfuzion’ as StackOverflow

Posted by Dan in Guides, Mac, Programming, 0 comments

Getting Back / Forward mouse buttons working in Mac OS X

If you want to use mouse buttons #4 and #5 to go forward / backward in Mac OS X out of the box you’re going to be disappointed, and end up with just a scroll icon appearing.

There’s a few utilities you can use to fix this:

  • Microsoft IntelliPoint – Only works with MS mice, doesn’t seem to work in Mountain Lion
  • Logitech Control Centre – Only works with Logitech mice, apparently quite buggy now
  • Razer software – not tested, will only work with Razer mice anyway
  • Steermouse – Getting increasingly flakey with new OS X versions
  • USB Overdrive – Not been in development since Snow Leopard, doesn’t seem to work 100% of the time anymore
  • ControllerMate – Works!

ControllerMate to the rescue!

ControllerMate is actively developed & maintained, and offers an incredible amount of customisation for all HID peripherals. So not only will it sort out your back / forward issue, it’ll also solve the mouse acceleration issue – if that’s a problem for you. This guide will cover back / forward only, though.

1. First download and install ControllerMate.

2. Reboot and launch ControllerMate.

You’ll now be presented with a scary as hell screen that looks like you’re laying out circuit boards, rather than fixing a major limitation in OS X.

The diagrams in place on first launch are a kind of mini tutorial, telling you how you can do a few things. You can either leave them in place for future reference, or delete them to clean up the view.

The first step is to create a new Programming Group:

3. To do this, right-click in the sidebar and select ‘Create Programming Group”.

4. Afterwards, right-click on the new group, and select ‘Create Programming Page’.

5. Now right-click on the new group again, point to ‘Create Driver Configuration’, then select your mouse.

You can name your new items in the ‘Inspector’ window to the right.

6. Click on your programming page to display an empty grid.

7. In the ‘Palette’ to the right, select ‘Controllers’ from the drop down list. Find your mouse, then drag button #4, and button #5 to the grid.

8. Now select ‘Output’ from the drop down list in the Palette. Drag an instance of ‘Keystrokes Building Block’ underneath each of your mouse button instances.

You should now have something like this (without the green lines):

9. Link the blocks, by dragging from the button’s green hotspot, to the action’s green hotspot. Just as in the screenshot above.

10. Click on the keystroke block for button #4. In the Inspector window, click on the ‘Keys’ tab, then click on ‘Capture’. Enter they key combination for ‘Back’ (Command + [), then press stop.

If the command doesn’t appear correctly, click on ‘Open Keystrokes Palette’, and drag the buttons from the virtual keyboard to the window, as seen above.

11. Do the same for button #5’s keystroke block, but this time use the command for forward (Command + ]).

12. Click on the driver configuration item in the sidebar, and set buttons #4 and #5 to ‘None’.

You’re now done! Backward / Forward should work immediately in all apps.

But now my VM / Other App doesn’t respond to buttons #4 and #5!

This is a problem as a result of disabling the buttons and remapping them to forward / back. Fortunately there is a solution!

  1. Click on the group in the sidebar
  2. In the ‘Inspector’ window, check ‘Activate items when these applications are:’, select ‘running’
  3. Add all of the apps that you want to add back / forward support to the list.

Now the mouse will work in all applications. If an app supports backward / forward, remember to add it to the list above.

More VM

Not all VMs support the extra mouse buttons, even if they’re receiving them. If you’re having trouble, try following my follow-up guide for Parallels.

Posted by Dan in Guides, Mac, 22 comments

Network Order and String Encoding

As a follow-on from my post on floating point values and endian swapping, I thought I’d write an article on strings. String encoding is fairly complicated due to the fact that we’re now living in a large global community – ASCII simply won’t cut it any more. On the positive side, if you only need ASCII you can send it across the network as-is. Since it’s only a single byte, there is no worry about endianness.

The problem is when dealing with string encoding that can go over a single byte, so-called multi-byte encoding. This is very likely if you need to support languages other than English. Rather than worry about endianness, BOMs, and other character encoding headaches; may I humbly suggest you try UTF-8. UTF-8 is completely backwards-compatible with ASCII, yet supports the entire unicode character set. It uses the minimum number of bytes for each character (good for saving bandwidth) and is inherently immune to endian issues (for for your sanity). In C# encoding to UTF-8 couldn’t be simpler:

Encoding.UTF8.GetBytes(myString);

The only issue with UTF-8 is that you can’t just say that the string is X number of bytes long based on the number of characters. Characters can require anywhere from 1 byte to 6 bytes. The simplest solution to this problem is to encode the string into a byte array, then prefix with an int that contains the length of the entire string in bytes. When reading the string back in, you can read in the first int then read however many bytes the int specifies.

Posted by Dan in C#, Guides, 0 comments