Swift-ly becoming a Vapor 3 web developer on Windows

Last summer I started building a web application in Swift, using the excellent Vapor framework. Since then I have been trying to persuade students to take up a Swift web project. Mostly they are reluctant because they “don’t have a Mac”. To which I reply, “run it on Docker”. And then I never see them again! So I thought I would try to setup Docker on Windows myself and go through the process of building and running a Vapor web app.


Prerequisites

  • Docker for Windows requires Windows 10 (64-bit, Pro or Professional) because it uses Microsoft’s Hyper-V system. (If you have Windows 7 or 8 then you will have to use Docker Toolbox instead.)
  • Memory — I was able to get this working on 4GB of RAM(!), but you will get much better performance with 8GB or more.

Step 1: Setup Docker for Windows

Download Docker for Windows and install it. After your installation, open a Command Prompt window and enter docker —-version to check that docker is working.

Next, open your Docker settings and go to the Network page.

Make a note of the IP address, most likely it will be 10.0.75.1. This will be the address of your website later!

If your PC is not the speediest of creatures then you can reduce the CPU cores or RAM usage on the Advanced tab of the Docker settings.

Step 2: Install an editor with Swift support (optional)

I’m going “all in” on Microsoft products today, so I installed Visual Studio Code (an open source text editor — Visual Studio’s cool younger brother) because it supports a ton of languages. Another choice is Atom. Both are good for editing the languages we need: Swift, Leaf, HTML, JS, CSS.

On the Welcome page, there is a section under “Customize” entitled “Tools and languages”. From here, search for “swift” and I picked the one with the most installs (Swift Language by Martin Kase).

This will give us syntax highlighting for Swift files. Unfortunately there isn’t any way to get Swift code completion on Windows yet (as far as I am aware) so VS Code is not going to have the power of Xcode any time soon.

Step 3: Build a Docker container for running Swift/Vapor

You are going to create a separate folder for your Dockerfile that builds a Vapor image. Later, we will create another folder for each project.

a) Create a folder called vapor (I will assume you did this inside the Documents folder).

b) Create a file called Dockerfile inside the folder (no extension), and copy the following code into the file.

FROM ubuntu:16.04
# Install CURL
RUN apt-get update && \
apt-get -y install curl && \
rm -rf /var/lib/apt/lists/*;
# Get Vapor repo including Swift
RUN curl -sL https://apt.vapor.sh | bash;
# Installing Swift & Vapor
RUN apt-get update && \
apt-get -y install swift vapor && \
rm -rf /var/lib/apt/lists/*;
WORKDIR /app

The Dockerfile is the recipe for building a Docker image, which can then be used to run commands in a container. You can see that the image is based on Ubuntu 16.04 and installs Swift and Vapor.

c) Back on the Command Line, go to your Documents folder (cd Documents) and then use docker to build your image:

docker build -t myvapor vapor
Get a cup of tea… this is going to take a while!

d) Test that you can run vapor:

docker run --rm myvapor vapor version

All being well, you should see this:

Step 4: Create a Vapor project

I will assume you still have the Command Prompt open and you are currently in the Documents folder.

a) Run a new Docker container interactively, connecting your Documents folder to the /app folder and forwarding port 8080.

docker run --rm -it -v C:\Users\Ant\Documents:/app -p 8080:8080 myvapor

(The first time you run this, Docker for Windows should notify you to share the C:\ drive. You must agree to this.)

“Share it”

b) Now we are inside the container, use the Vapor toolbox to create a new project.

vapor new HelloWorld

c) Move into the HelloWorld folder and build the project.

cd HelloWorld
vapor build

If it builds successfully then you should see this:

d) Run the project. Note that we must specify the hostname else we will not be able to see if from outside the container.

vapor run serve --hostname=0.0.0.0

e) Open your web browser at http://10.0.75.1:8080/hello. Note, you cannot access it on localhost because it is running inside the Hyper-V virtualisation.

That’s it, you are running Swift and Vapor on your Windows machine!

Step 5: Improving the build/run workflow

You already have completed all the steps required to build and run a Vapor web app, but all those commands are quite a lot to remember/type everytime you want to build and run. In just a moment, I’m going to create a batch file to simplify the commands. But first, I would like to show you that you can run the build command directly from the Command Prompt:

docker run --rm -v C:\Users\Ant\Documents\HelloWorld:/app myvapor vapor build

Note that we connect our project folder (HelloWorld) directly, then the container starts in that directory and runs the build command. Similarly, we can run the project:

docker run --rm -v C:\Users\Ant\Documents\HelloWorld:/app -p 8080:8080 myvapor vapor run serve --hostname=0.0.0.0

We can create a batch file on Windows to make typing these commands easier. Create a new file called vapor.bat in your HelloWorld folder, then copy in the following code.

@echo off
docker run --rm --name vapor -v %cd%:/app -p 8080:8080 myvapor vapor %*

Now if you are in your HelloWorld folder, you can build and run as follows (directly from Command Prompt):

vapor build
vapor run serve --hostname=0.0.0.0

Next, move vapor.bat to your vapor folder and add that folder to your Windows path. You are good to run these commands from any of your project folders now.

Important note: when you do a vapor run serve, if you use Ctrl-c to stop the process then you will see the a “terminate process” message. Unfortunately this does not kill the child process (vapor), so you need to manually use docker stop vapor. Else when you run again you will get an error that port is already in use. (Maybe someone can suggest a better way to end the child process automatically so that I can use Ctrl-c similar to *nix?)

Next steps

If you need to update the version of Vapor, or the version of Swift, then you will need to rebuild the myvapor container as explained in Step 3(c).

docker build --no-cache -t myvapor vapor

When you are not developing then you can quit Docker for Windows from the tray to free up resources for other tasks, and start it up again as necessary. As long as you have Docker for Windows running, you can make use of your vapor batch file to run the Vapor toolbox. For example, you can create a new web project using a template by opening the Command Prompt and running:

vapor new --template=https://github.com/antonyharfield/vapor-web-template WebTemplate

With this magic complete, your friends will think you have got a native Vapor toolbox running on Windows! Go ahead and impress your Mac friends with your awesome Swift skills. :)