This is Part 3 of a three part series on how to create and deploy an Elixir application that will automatically scale on Kubernetes. Be sure to visit Part 1 and Part 2 if you need to catch up. If you just want to see the source code it’s available here: https://github.com/groksrc/el_kube and if you just want a summary of the commands the slide deck from the original talk is available here.

In Part 1 of this series we created an Elixir app named el_kube that is configured to automatically join an erlang cluster and in Part 2 we created a Docker container for it so that we can run it on Kubernetes (k8s) and tested it, ending on Step 15. Here in Part 3 we’re going resume our previous work and run the container in k8s by way of minikube. Again, all of the commands I show below are issued from the root of the project directory. Let’s get started!

16: Create a directory for your k8s files

Kubernetes is configurable in a number of different ways, but generally, I recommend using a file-based approach over the CLI. The primary reason is that often you’ll want a history of the commands that have been run on your cluster that the CLI can’t provide you as well as the ability to more easily reason about how you’re configuring the cluster. The CLI command and arguments can become exceedingly verbose when doing anything more than just trivial examples, so I’ll rely on the file-based approach going forward.

$ mkdir k8s

17: Create a Persistent Volume Claim

If you think about what a k8s cluster is, it’s essentially a set of physical machines, all with some of their own internal storage, as well as a network connection to shared storage, usually like a SAN or something. A database needs a permanent spot to put files that will continue to exist no matter what happens to the running containers or the nodes of the k8s cluster, and that’s what a Persistent Volume Claim (PVC) gives you. Let’s create a new file called k8s/pvc.yaml and then apply it to our minikube cluster.

kind: PersistentVolumeClaim
apiVersion: v1
metadata:
  name: postgres-pvc
  labels:
    app: postgres
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi

This file defines a PVC, sets its name to postgres-pvc and applies the app: postgres label. The labels are arbitrary key/value pairs (which is true on all k8s configs) and the spec that follows sets the accessModes for the container and defines the amount of space. In our case, we’re defining a ReadWriteOnce mode which means that only one connection at a time is allowed, which is fine because we’re only going to have one container (the Postgres DB container) accessing the PVC and we ask for 1 GB of storage.

Once you have created and saved the file above, issue the following command to add the PVC to the cluster:

$ kubectl create -f k8s/pvc.yaml
persistentvolumeclaim/postgres-pvc created

18: Create the DB using the PVC

Next, let’s define a Deployment for the Postgres database and call it k8s/db.yaml. This config will start a Postgres container and mount the PVC to the mountPath defined under volumeMounts. This way, any DB container that boots will find the files in the same location, which is the location the container expects, and it will pick up where it left off. Here is the content for the db.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: db
spec:
  replicas: 1
  strategy:
    type: Recreate
  selector:
    matchLabels:
      app: postgresql
  template:
    metadata:
      creationTimestamp: null
      labels:
        app: postgresql
    spec:
      containers:
      - env:
        - name: POSTGRES_DB
          value: el_kube_prod
        image: postgres:9.6
        name: db
        ports:
        - containerPort: 5432
        resources: {}
        volumeMounts:
        - mountPath: /var/lib/postgresql/data
          name: data
      hostname: db
      restartPolicy: Always
      volumes:
        - name: data
          persistentVolumeClaim:
            claimName: postgres-pvc

Notice again we’re passing the POSTGRES_DB environment variable to the container and we’re also declaring a volume named data that uses the PVC we defined above. We’re also applying the app: postgresql label to this container. We’ll see how this comes in to play in the next config file.

Notice again we’re passing the POSTGRES_DB environment variable to the container and we’re also declaring a volume named data that uses the PVC we defined above. We’re also applying the app: postgresql label to this container. We’ll see how this comes in to play in the next config file.

Now that the file is saved, let’s create the deployment on the cluster:

$ kubectl create -f k8s/db.yaml
deployment.extensions/db created

At this point you should be able to see that the pod is up and running:

$ kubectl get pods
NAME                  READY   STATUS    RESTARTS   AGE
db-84c67d88cf-d2xss   1/1     Running   0          13s

Great! But there’s a problem. This container has a dynamic name and IP address that’s assigned to it and we need a static IP address or DNS name to give to our Phoenix nodes so they know where to connect. What to do? A k8s service will do the trick!

19: Create the DB service

Back in your editor, let’s now create a file named k8s/db-svc.yaml and add the following content to it:

apiVersion: v1
kind: Service
metadata:
  labels:
    app: postgresql
  name: db
spec:
  ports:
  - name: postgres
    port: 5432
    targetPort: 5432
  selector:
    app: postgresql

This file defines a k8s Service and gives it the name db . The key point here is that inside a container on the cluster the DNS name of db can be resolved once this service is in place. The spec says that the service will have a port named postgres and containers outside the service will connect on port 5432 while containers under the service will use the targetPort, also 5432. How are containers included as a part of the service? With the selector. Like I mentioned previously, the label app: postgresql is applied to our database container. When the k8s management engine sees that container (pod really) labeled with that key/value pair it will automatically start sending traffic directed at that service to those containers.

Now that we understand what this does, let’s fire it up on the minikube cluster:

$ kubectl create -f k8s/db-svc.yaml
service/db created

20: Create the el_kube private and public services

Next, let’s create a private Service for the app. This one is going to be a little different than the service for the database though. Remember, the last service assigned a static IP address to the database server. In this case, when we query DNS we don’t want back a static IP. Instead what we’d like to get is a list of IP addresses to give to peerage. That’s how peerage will know what containers in the cluster are running the beam and it will attempt to join them together.

Create a file name k8s/el-kube-private-svc.yaml and add the following content:

apiVersion: v1
kind: Service
metadata:
  name: el-kube-private
spec:
  clusterIP: None
  ports:
  - name: epmd
    port: 4369
  selector:
    app: el-kube

Here the main difference is that we’re setting the clusterIP to none. This way a single static address is not assigned to the service, but instead, any pods with the label app: el-kube will be returned in the DNS query.

With this file in place let’s create the service on the minikube cluster:

$ kubectl create -f k8s/el-kube-private-svc.yaml

Now let’s create a public service so that we can reach the Phoenix app from our host. This service will expose the containers running the elixir application on port 4000 to our host.

apiVersion: v1
kind: Service
metadata:
  name: el-kube-public
spec:
  ports:
  - name: http
    port: 4000
  selector:
    app: el-kube
  type: LoadBalancer

And now create the service in minikube.

$ kubectl create -f k8s/el-kube-public-svc.yaml

21: Push the container to the minikube cache

At this point we’re almost ready to deploy the app container. But there’s another problem. We haven’t pushed it to a cloud repo anywhere that minikube can pull it from. That’s ok, let’s use a shortcut instead. We can actually just push the image straight into the minikube image cache. Execute the following command to do this:

$ minikube cache add el_kube:latest

22: Create the el_kube Deployment

Now that the container is in place on the k8s cluster, we’re ready to create the deployment. Switch back to your editor and create a file named k8s/el-kube.yaml. Add the following content to the k8s/el-kube.yaml file:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: el-kube-deployment
  labels:
    app: el-kube
spec:
  replicas: 3
  selector:
    matchLabels:
      app: el-kube
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 34%
      maxUnavailable: 34%
  template:
    metadata:
      name: el-kube
      labels:
        app: el-kube
    spec:
      containers:
      - name: el-kube
        image: el_kube:latest
        imagePullPolicy: Never
        env:
          - name: APP_HOST
            value: el-kube.com
          - name: DB_URL
            value: ecto://postgres:postgres@db/el_kube_prod
          - name: HOSTNAME
            valueFrom:
              fieldRef:
                fieldPath: status.podIP
          - name: PORT
            value: "4000"
          - name: RELEASE_COOKIE
            value: el-kube-secret-cookie
          - name: SECRET_KEY_BASE
            value: super-secret-key-base
          - name: SERVICE_NAME
            value: el-kube.default.svc.cluster.local
        resources: {}
        securityContext:
          privileged: false
          procMount: Default
        terminationMessagePath: /dev/termination-log
        terminationMessagePolicy: File
      dnsPolicy: ClusterFirst
      restartPolicy: Always
      schedulerName: default-scheduler
      securityContext: {}
      terminationGracePeriodSeconds: 30

There’s a lot going on here, probably too much to explain in a blog post. Much of this I picked up from other configs, but you should recognize the important bits. We’re creating a Deployment named el-kube-deployment and we’re matching containers with the label app: el-kube We’re also configuring 3 replicas, this is our 3 node cluster, and we’re setting our update strategy. This will tell k8s how many containers to create/terminate at a time so you get a smooth rollout. The spec uses our container label and note we set the imagePullPolicy: Never so that it will use the image we built locally.

With this file in place let’s fire up the app. Run the following command from your terminal:

$ kubectl create -f k8s/el-kube.yaml
deployment.apps/el-kube-deployment created

Let’s see if it worked!

23: Check your work

First thing first, make sure your containers (pods) are running:

$ kubectl get pods
NAME                                 READY   STATUS    RESTARTS   AGE
db-84c67d88cf-d2xss                  1/1     Running   0          9m56s
el-kube-deployment-ffc6db99c-9p7n5   1/1     Running   0          12s
el-kube-deployment-ffc6db99c-dt4f4   1/1     Running   0          12s
el-kube-deployment-ffc6db99c-qqd22   1/1     Running   0          12s

You should have 4 pods, one DB and 3 el-kube. You should issue this command a couple of times to make sure that they aren’t crashing. If they stay up for 30s or so you should be good.

Next, let’s see if we can reach the phoenix web application. Minikube has a built-in command that will expose LoadBalancer services. This should open the browser on your machine and show you the running application. To view the phoenix app:

$ minikube service el-kube-public

Now let’s connect to one and see if the peerage configuration worked. Issue the following command to connect to a running container. Make sure to use the pod's names your system created, they will be different than mine:

$ kubectl exec -it el-kube-deployment-ffc6db99c-9p7n5 sh

The sh at the end of the command overrides the default CMD command from the container, so you should be dropped into the shell on that running container in the WORKDIR directory.

Now, let’s see if we can connect to the beam as we did before in Part 1.

/usr/local/el_kube # bin/el_kube remote

Erlang/OTP 22 [erts-10.4.4] [source] [64-bit] [smp:2:2] [ds:2:2:10] [async-threads:1] [hipe]

Interactive Elixir (1.9.0) - press Ctrl+C to exit (type h() ENTER for help)

iex(el_kube@172.17.0.9)1>

If you see this that is a good sign. You’re now connected remotely to the beam cluster. Let’s list the Nodes and see if everything is hooked up.

iex(el_kube@172.17.0.9)1> Node.list
[:"el_kube@172.17.0.7", :"el_kube@172.17.0.8"]

If you get two nodes back, stop and breathe in that sweet, sweet success. You’ve done it! Don’t be surprised that there are only two nodes in the list. Node.list/0 returns remote nodes, not the node you’re currently connected to, so everything is working.

Next, let’s make sure the database is connected:

iex(el_kube@172.17.0.9)2> ElKube.Repo.query("select 1 as testing")
{:ok,
 %Postgrex.Result{
   columns: ["test"],
   command: :select,
   connection_id: 95,
   messages: [],
   num_rows: 1,
   rows: [[1]]
 }}

If you get back the ok tuple then you’re golden. Everything is connected and beers are to be had all around. 🍻

But wait! There’s more! Wouldn’t it be incredible if we could just change the el-kube-deployment config and automatically add new nodes to the erlang cluster? Well, we can!

24: Grow your cluster’s cluster

Let’s change the number of deployment replicas to 5 and make sure that the erlang cluster connects:

$ kubectl scale deployment el-kube-deployment --replicas 5
deployment.apps/el-kube-deployment scaled

Let’s see if the new pods came up:

$ kubectl get pods
NAME                                 READY   STATUS    RESTARTS   AGE
db-84c67d88cf-d2xss                  1/1     Running   0          12m
el-kube-deployment-ffc6db99c-4nw5k   1/1     Running   0          6s
el-kube-deployment-ffc6db99c-9p7n5   1/1     Running   0          2m49s
el-kube-deployment-ffc6db99c-dt4f4   1/1     Running   0          2m49s
el-kube-deployment-ffc6db99c-gzwqf   1/1     Running   0          6s
el-kube-deployment-ffc6db99c-qqd22   1/1     Running   0          2m49s

They did! Did they connect??

$ kubectl exec -it el-kube-deployment-ffc6db99c-9p7n5 sh
/usr/local/el_kube # bin/el_kube remote
Erlang/OTP 22 [erts-10.4.4] [source] [64-bit] [smp:2:2] [ds:2:2:10] [async-threads:1] [hipe]

Interactive Elixir (1.9.0) - press Ctrl+C to exit (type h() ENTER for help)
iex(el_kube@172.17.0.8)1> Node.list
[:"el_kube@172.17.0.6", :"el_kube@172.17.0.7", :"el_kube@172.17.0.9",
 :"el_kube@172.17.0.10"]

They did!!! 🎉 🎉 🎉

Ahh, that’s the stuff. That’s why I do this job. So I hope you’ve enjoyed this series. Here are a few resources to follow up with if you’d like to dive a little deeper.

Resources

The In Action series by Manning was incredibly helpful in getting me up to speed on all of the technologies I’ve covered in this series. I highly recommend them:

• https://www.manning.com/books/elixir-in-action-second-edition
• https://www.manning.com/books/kubernetes-in-action
• https://www.manning.com/books/docker-in-action-second-edition

If you’re stuck on versions of Elixir before 1.9, don’t worry, there’s hope. I actually originally implemented this in 1.8.1 with Distillery right before 1.9 dropped. It’s a little harder to work with but this is still definitely doable using the concepts applied here. Do check out Distillery if that’s the way you need to go: https://github.com/bitwalker/distillery

I also found these articles helpful in my quest, I stand upon the shoulder of giants:

• https://medium.com/polyscribe/a-complete-guide-to-deploying-elixir-phoenix-applications-on-kubernetes-part-1-setting-up-d88b35b64dcd
• https://stackoverflow.com/questions/42564058/how-to-use-local-docker-images-with-minikube
• https://stackoverflow.com/questions/52890718/kubectl-run-is-deprecated-looking-for-alternative
• https://elixir-lang.org/blog/2019/06/24/elixir-v1-9-0-released/

And that’s about it. I hope you’ve enjoyed reading this series and it’s helpful in your day-to-day. It took me quite a while to piece all of this together, so hopefully, you don’t have to. Enjoy!

-g

This is Part 2 of a three part series on how to create and deploy an Elixir application that will automatically scale on Kubernetes. Part 1 and Part 3 are also available. If you just want to see the source code it’s available here: https://github.com/groksrc/el_kube and if you just want a summary of the commands the slide deck from the original talk is available here.

In Part 1 of this series, we created an Elixir application that is ready to be deployed in an erlang cluster configuration. The next step (Step 12) is to create the Docker container for the app and make sure everything spins up. In this post I’m using a default install of the latest Docker for Mac, but this should work on Linux and Windows as well.

12: Create the Dockerfile and .dockerignore

Let’s start by creating a Dockerfile and .dockerignore in the root of the folder:

$ touch Dockerfile && touch .dockerignore

13: Edit the Dockerfile and .dockerignore

Now paste in the content for the Dockerfile and we’ll look at what it does:

FROM elixir:1.9 AS builder

ENV MIX_ENV=prod

WORKDIR /usr/local/el_kube

# This step installs all the build tools we'll need
RUN curl -sL https://deb.nodesource.com/setup_13.x | bash - && \
    apt-get install -y nodejs && \
    mix local.rebar --force && \
    mix local.hex --force

# Copies our app source code into the build container
COPY . .

# Compile Elixir
RUN mix do deps.get, deps.compile, compile

# Compile Javascript
RUN cd assets \
    && npm install \
    && ./node_modules/webpack/bin/webpack.js --mode production \
    && cd .. \
    && mix phx.digest

# Build Release
RUN mkdir -p /opt/release \
    && mix release \
    && mv _build/${MIX_ENV}/rel/el_kube /opt/release

# Create the runtime container
FROM erlang:22 as runtime

WORKDIR /usr/local/el_kube

COPY --from=builder /opt/release/el_kube .

CMD [ "bin/el_kube", "start" ]

HEALTHCHECK --interval=30s --timeout=30s --start-period=5s --retries=2 \
 CMD nc -vz -w 2 localhost 4000 || exit 1

At the top of the file we start with an Elixir base container image and set our MIX_ENV environment variable to prod and configure our working directory to /usr/local/el_kube

For those not familiar with Docker, you can think of it like this. The docker runtime reads in the Dockerfile and executes each command from top to bottom. So first it starts the base container image, then it sets the environment variable. The WORKDIR command creates a directory at that path and changes into it.

We then execute the bash script that follows the RUN command to add our dependencies necessary to compile the app.

Next we COPY the code that’s in our working directory (where we ran the command) into the container and compile it. Then we compile the javascript and call the mix release command to generate the release.

ProTip: Don’t forget the .dockerignore file. You don’t want the _build directory from your development host winding up in the container. We’ll add a .dockeringore next.

Next, you find another FROM command. What is this you ask? Great question! It’s a two-phase container build. Huh? Right. So each line of the Dockerfile creates a “layer” in Docker parlance that is used to compose the container. In our release container we don’t actually want or need all of the dependencies necessary to compile the app. We just want the output of all of that.

So in the first phase of the build we compile, and in the second phase we copy the results from the first phase and include only the dependencies we need to actually execute the application. The second phase of the container build process starts with the second FROM command and pulls the base erlang:22-alpine image (which is the base of the first container) and copies in the one dependency on gcc along with the output from the first phase of the build.

Then we set the CMD to execute at startup and end with a HEALTHCHECK. The HEALTHCHECK here is didactic, you don’t really need it but it’s nice to show. Kubernetes will run the command in the health check at the configured interval, and if it fails the specified number of times it will kill the container. In practical terms what it means for this project is that the container would fail and a new one would be brought up and automatically rejoin the cluster. Pretty cool!

Now that we’ve looked at the Dockerfile let’s throw in a few lines to the .dockerignore:

_build/
.elixir_ls/
.git/
.vscode/
deps/
priv/static/
k8s/
test/
.dockerignore
.env
.formatter.exs
.gitignore
.travis.yml
Dockerfile
README.md

This is my .dockerignore so customize as you see fit. Just don’t remove that top line! Now we’re ready to build the container.

14: Build the container

Issue the following command to build the container. You should see the success messages that follow.

$ docker build -t el_kube:latest .
...
Successfully built 1a5ed90cc8c0
Successfully tagged el_kube:latest

15: Smoke test the container

Now let’s see if it works. We’re going to use Docker to create a private network, a Postgres container and our app container to make sure we’re all communicating. The benefit of creating the private docker network is that all containers on the network will be able to access any port, and you’re not going to conflict with your host. You could, of course, use the default bridge network, but then you’d have to use the deprecated --link argument to get the containers talking. More details about this are available in the docker network docs.

$ docker network create el-kube-net
80a3e59c2cc82c7d2e4aff2d2a8a2daf14f3731f0e7604777be5f925b99b0006

Now that the network is available, let’s start a Postgres container and join it to the el-kube-net network.

$ docker run --rm -d \
  -h db \
  -e POSTGRES_DB=el_kube_prod \
  -p 5432 \
  --name db \
  --network el-kube-net \
  postgres:9.6
116714d3b9b03f8730bd2c942d092ea3c2ad0d97fc955e656e8e73c96ca40ca0

Here we’re telling docker to run the postgres:9.6 image. The --rm flag will remove the container files when the container stops. The -d flag sets it to run as a daemon. The -h flag is for the DNS name of the container inside the el-kube-net network and setting this allows other containers to refer to it as db. The -e flag is nice because here we’re passing the POSTGRES_DB environment variable. The Postgres container will look for this variable to be set and if it finds it then it will automatically create a database with the supplied name after the database engine starts. No need to issue a CREATE DATABASE command.

The --name flag tells Docker what this container will be named. That’s different than the -h flag which is how it’s referred to inside the network. This is from outside the network at the terminal on your Docker host. And finally, the --network flag joins the container to the user-defined bridge network we created above.

Finally! Let’s start the app. We pass all of the environment variables describe in Part 1 of the series, in addition to the --network and --publish flags. The --publish flag I didn’t cover previously, it exposes port 4000 on the host (outside the docker network) to whatever is bound to port 4000 inside the network, allowing traffic to pass through.

$ docker run -it -d --rm \
-e DB_URL=ecto://postgres:postgres@db/el_kube_prod \
-e RELEASE_COOKIE=secret-cookie \
-e SECRET_KEY_BASE=your-secret-key \
-e SERVICE_NAME=el-kube \
-e APP_HOST=localhost \
-e PORT=4000 \
--network el-kube-net --publish 4000:4000 el_kube:latest
f6cba46a29c079284b7625554105640e4a5beaff1bdf417d6fa623c26948d26b

If you got that final hash back it’s a good sign. Let’s make sure our containers are up:

$ docker container ls 
CONTAINER ID        IMAGE               COMMAND                  CREATED              STATUS                            PORTS                     NAMES
f6cba46a29c0        el_kube:latest      "bin/el_kube start"      9 seconds ago        Up 8 seconds (health: starting)   0.0.0.0:4000->4000/tcp    reverent_hugle
116714d3b9b0        postgres:9.6        "docker-entrypoint.s…"   About a minute ago   Up About a minute                 0.0.0.0:32768->5432/tcp   db

This is a bit ugly, but if you see two containers you’re in pretty good shape. Make sure you can again browse to http://localhost:4000. If so, you’re in business. The container is working and now we’re ready to spin up on Kubernetes.

EDIT 01/2020: I recently updated the source code to make it easier to smoke test the application. Now all you need to do is:

$ docker-compose up

See the source code repository for the docker-compose.yaml and docker.env files that make this work

In Part 3 of the series, we’ll put these first two pieces together and get our erlang cluster running on our minikube cluster. It’s a cluster of clusters. You might even say, “it’s a real cluster.”

-g

This is Part 1 of a three part series on how to create and deploy an Elixir application that will automatically scale on Kubernetes. Part 2 and Part 3 are also available. If you just want to see the source code it’s available here: https://github.com/groksrc/el_kube and if you just want a summary of the commands the slide deck from the original talk is available here.

This series is designed to show you how to create an auto-scaling Elixir cluster using Elixir 1.9 and Kubernetes. What does that mean? Well, it means that the application will start, automatically connect in an erlang cluster configuration, and then automatically add and remove erlang nodes as the Kubernetes (k8s) configuration changes.

In Part 1 we’ll look at creating the application itself. Part 2 will show you how to Dockerize the application and confirm that the container works. And finally in Part 3 we will launch the application on Kubernetes using minikube and demonstrate how it automatically scales as the deployment changes. Let’s get started!

Part 1 — Creating the App

Before you begin you’ll want to make sure that you have Elixir 1.9 installed, along with OTP 22. You’ll also want to make sure that you’re using the current version of Phoenix which is v1.4.9 at the time of this writing. Also, make sure that minikube is installed and kubectl is configured to use the minikube context.

Our application is going to be named el_kube and as an aside, all of this code is available in my repo at https://github.com/groksrc/el_kube. I start with an empty project at master, then at each branch I change only the files necessary to proceed to the next step. I originally presented this work at a Simpli.fi tech talk so you should be able to issue the commands and make the file changes straight from the slide deck as well. If you run into any trouble, send me a reply and I’ll try to help out.

00: New Project

From the working directory on your development machine let’s start a new Phoenix project. I called mine el_kube because elixir and Kubernetes mashed up you know.

$ mix phx.new el_kube

Be sure to say Yes when asked to “Fetch and install dependencies? [Yn]”

01: Open the project

Now let’s switch into the project folder and open our editor. All of the following commands are issued from the project folder’s root directory. Also, I’m using vscode with the ElixirLS plugin, so you’re working with git you will probably want to add the .elixir_ls/ folder to the .gitignore.

$ cd el_kube && code .

02: Edit mix.exs

Once the project is open in your editor pop over to the mix.exs file that’s at the project root. We’re going to make three changes here.

First, update the project key from 1.5 to 1.9. Using Elixir 1.9 is required for this project.

elixir: "~> 1.9",

Next, we’re going to add a dependency on peerage and set peerage to boot as an extra_application on startup. Like it says in its readme, Peerage helps your erlang nodes find each other. We’ll be using it to provide the secret sauce for getting this to work.

def application do
  [
    mod: {ElKube.Application, []},
    extra_applications: [:logger, :runtime_tools, :peerage]
  ]
end

And...

defp deps do
    [
      {:phoenix, "~> 1.4.9"},
      {:phoenix_pubsub, "~> 1.1"},
      {:phoenix_ecto, "~> 4.0"},
      {:ecto_sql, "~> 3.1"},
      {:postgrex, ">= 0.0.0"},
      {:phoenix_html, "~> 2.11"},
      {:phoenix_live_reload, "~> 1.2", only: :dev},
      {:gettext, "~> 0.11"},
      {:jason, "~> 1.0"},
      {:plug_cowboy, "~> 2.0"},
      {:peerage, "~> 1.0"}
    ]
  end

Once the three changes are mix.exs you can save it and close it up. Don’t forget to run $ mix deps.get if your editor doesn’t do that for you.

02: Initialize the release

Next, we’re going to use the new mix command to generate some template files for us. These template files are used to help generate the scripts which are executed when the application starts up.

$ mix release.init
* creating rel/vm.args.eex
* creating rel/env.sh.eex
* creating rel/env.bat.eex

This command generates three different Elixir templates for you in the rel directory. We’ll ignore the env.bat.eex. I’m not on windows, but if I were I would need to apply the relevant changes there. Instead, I’m going to update env.sh.eex to set some environment variables for me at startup.

03: Update rel/env.sh.eex

Inside rel/env.sh.eex we’re going to uncomment the lines that export RELEASE_DISTRIBUTION and RELEASE_NODE. Then change the localhost IP to an environment variable that will be passed dynamically. Make the following changes to the file:

export RELEASE_DISTRIBUTION=name
export RELEASE_NODE=<%= @release.name %>@${HOSTNAME}

Configuring the RELEASE_DISTRIBUTION environment variable to name will configure the erlang beam to be able to connect to other nodes in the cluster using the long name format. The RELEASE_NODE is the name of the erlang node using the long name format. See the mix task docs for more details on configuring these environment variables.

For our purposes, we’re going to dynamically pass in the IP address that k8s assigns to the container as the HOSTNAME but you can use a valid cluster DNS name here as well. Save that file up and we’re on to the next.

04: Remove config/prod.secret.exs

This file won’t be used, so we’re going to drop it.

$ rm config/prod.secret.exs

05: Create config/releases.exs

Instead, we’re going to use the new releases.exs file to help us dynamically configure our application at startup. Let’s create the file and open it in our editor.

$ touch config/releases.exs

06: Edit config/releases.exs

Now we’re ready to set up our dynamic configuration. Paste this into the file:

import Config

service_name = System.fetch_env!("SERVICE_NAME")
db_url = System.fetch_env!("DB_URL")
secret_key_base = System.fetch_env!("SECRET_KEY_BASE")
port = System.fetch_env!("PORT")

config :el_kube, ElKube.Repo, url: db_url

config :el_kube, ElKubeWeb.Endpoint,
  http: [port: port],
  secret_key_base: secret_key_base,
  url: [host: {:system, "APP_HOST"}, port: {:system, "PORT"}]

config :peerage, via: Peerage.Via.Dns,
  dns_name: service_name,
  app_name: "el_kube"

The service_name is going to be the internal DNS name of the application. In other words, a node on the cluster will be able to query DNS for the service_name and get a response with a list of IP addresses.

The db_url is the Postgres connection string. The secret_key_base is used for Phoenix to sign the cookies and the port is the port the web endpoint will listen on.

You’ll also notice there’s an APP_HOST environment variable sprinkled in to the ElKubeWeb.Endpoint as well. Phoenix is a bit of an odd-ball because it did allow some dynamic configuration on its own prior to Elixir 1.9. Here we’re just using that built-in construct to tell Phoenix to pull APP_HOST and PORT from the environment. These two values are used for its internal URL helpers. Save this file up, on to the next.

07: Edit config/prod.exs

Now let’s look at the production config file. As in prior Elixir releases, the environment specific configs are layered on top of the base config/config.exs, so here we can set some production specific stuff that can’t be changed. First, we need to remove the url key that’s been moved into config/releases.exs and next we need to add the endpoint config key/value pair server: true

This tells Phoenix to start the webserver endpoint when the server starts up. Why that’s not the default in this file I’m not sure, but let’s make those changes and move on. Your config/prod.exs file should now look like this.

use Mix.Config

# Lots of comments ...
config :el_kube, ElKubeWeb.Endpoint,
  cache_static_manifest: "priv/static/cache_manifest.json",
  server: true

# Do not print debug messages in production
config :logger, level: :info

# Lots more comments ...

Oh! And don’t forget to scroll down to the very bottom of the file and delete the import_config "config/prod.secrets.exs" I missed that on several run-throughs, so that’s why we deleted it earlier. It will now complain at us if we forget this step.

08: Edit config/config.exs

This step isn’t completely necessary. Of course you can configure your application however you want in real life. But for demonstration purposes we’re going to drop in some base Ecto config just so we can show that it does indeed get picked up. Open up the config/config.exs file and add the following:

config :el_kube, ElKube.Repo,
  adapter: Ecto.Adapters.Postgres,
  pool_size: 10

Again, all or none of this could be in here. In real life you’d probably want your pool_size to be configured from config/releases.exs so this is purely didactic.

09: Edit config/dev.exs

One last file change and we’ll be ready to start compiling. Let’s make peerage happy in the development environment, and also because we typically don’t run a cluster in development mode (which peerage complains vociferously about) let’s tell it to be quiet. Add the following to your config/dev.exs file:

config :peerage,
  via: Peerage.Via.List,
  node_list: [:"el_kube@127.0.0.1"],
  log_results: false

10: Compile

Now let’s switch to our terminal and execute the compilation and smoke tests. First we need to generate the digest files for the javascript side of Phoenix to be happy.

$ mix phx.digest
...
==> el_kube
Check your digested files at "priv/static"

Next let’s generate the release:

$ MIX_ENV=prod mix release
...
...
To list all commands:

  _build/prod/rel/el_kube/bin/el_kube

If you see the above, you’re making great progress! The last step is to create a database for our application to connect when it starts up.

$ mix ecto.create
The database for ElKube.Repo has been created

Now we’re ready to run the release and make sure it fires up. This command has to pass all of the environment variables we considered earlier in addition to one I didn’t talk about, the RELEASE_COOKIE. This one is also covered in the mix release task docs, but I wanted to touch on it here. The RELEASE_COOKIE is a sort of pre-shared key that the erlang beam uses to authenticate when nodes connect. It’s not strictly necessary here, but I wanted to introduce it here because you’ll be seeing it again in Part 3.

11: Smoke Test

Here is the command to start the app:

DB_URL=ecto://postgres:postgres@localhost/el_kube_dev \
RELEASE_COOKIE=foo \
SECRET_KEY_BASE=foo \
HOSTNAME=127.0.0.1 \
SERVICE_NAME=localhost.svc \
APP_HOST=localhost \
PORT=4000 \
_build/prod/rel/el_kube/bin/el_kube start

We covered what all of these environment variables do above so I won’t go over that again. What’s new here is that we’re actually executing our application and passing the start command. When you do this you should see the following:

15:20:47.765 [info] Running ElKubeWeb.Endpoint with cowboy 2.6.3 at 0.0.0.0:4000 (http)
15:20:47.765 [info] Access ElKubeWeb.Endpoint at http://localhost:4000

Now you can open your browser to that address or $ curl http://localhost:4000 and you should see a webpage come back. If it does then you’re in business!

Next, let’s confirm our database connectivity is working by launching another terminal and connecting to this running instance. Everything is the same as the previous command except this time instead of passing start at the end we’ll pass theremote argument:

DB_URL=ecto://postgres:postgres@localhost/el_kube_dev \
RELEASE_COOKIE=foo \
SECRET_KEY_BASE=foo \
HOSTNAME=127.0.0.1 \
SERVICE_NAME=localhost.svc \
APP_HOST=localhost \
PORT=4000 \
_build/prod/rel/el_kube/bin/el_kube remote

Here you should be dropped into an elixir prompt:

Erlang/OTP 22 [erts-10.4.4] [source] [64-bit] [smp:12:12] [ds:12:12:10] [async-threads:1] [hipe] [dtrace]

Interactive Elixir (1.9.1) - press Ctrl+C to exit (type h() ENTER for help)
iex(el_kube@127.0.0.1)1>

At this point you can issue an Ecto command and you should get back an :ok tuple.

iex(el_kube@127.0.0.1)1> ElKube.Repo.query("select 1 as test")
{:ok,
 %Postgrex.Result{
   columns: ["test"],
   command: :select,
   connection_id: 41993,
   messages: [],
   num_rows: 1,
   rows: [[1]]
 }}

If you made it this far, congratulations! You’re now ready to move on to Part 2 and Dockerize your application.

-g

Elixir + Kubernetes = 💜 (Part 1) was originally published in ITNEXT on Medium, where people are continuing the conversation by highlighting and responding to this story.

I’m currently working on a project that requires SSL on my development web server. Setting up a self-signed certificate with OpenSSL is reasonably straightforward and that had been working for a while. But then the requirement was added that the hostname could not be ‘localhost’. 🙄 Blame the vendor. Hello SAN (Subject Alternative Name) cert.

I found many examples online about how to do this with a config file, but I needed this to work in a simple one-liner. So here it is:

openssl req \
-x509 \
-newkey rsa:4096 \
-sha256 \
-days 3560 \
-nodes \
-keyout example.key \
-out example.crt \
-subj '/CN=<Your Cert Name>' \
-extensions san \
-config <( \
  echo '[req]'; \
  echo 'distinguished_name=req'; \
  echo '[san]'; \
  echo 'subjectAltName=DNS:localhost,<yourdomain>')

Just replace <Your Cert Name> with what you want to appear as the title, and <yourdomain> with the domain you want to impersonate. You can, of course, add additional domain names to the list. Just separate them with a comma (no space). You’ll then need to import the certificate to your certificate store and set the trust options according to your environment. That’s it!

-g

Step 1: Create a patch against your base branch

$ git diff master my_large_feature_branch > ../my_pr_patch

Step 2: Checkout a new branch

Create a new branch that will contain a subset of the changes in my_large_feature_branch

$ git checkout master
$ git checkout -b small_pr_one

Step 3: Apply Changes Selectively

Now apply the patch to your new small_pr_one branch. This will apply all of the changes from my_large_feature_branch to disk and allow you to stage things that can go individually.

$ git apply ../my_pr_patch

Once you’ve staged and committed whatever you want for small_pr_one it’s time to clean up.

Step 4: Stash the Remaining Changes

To stash everything that isn’t staged, including untracked files, run the following command.

git stash --include-untracked --keep-index

Now small_pr_one is clean and you can open a PR against it. Next move on to small_pr_two through small_pr_n until complete.

Step 5: Repeat 3 & 4 Until Done

If the next set of changes can be made independently then open small_pr_two against master. If you need what was in small_pr_one to keep going just branch from there.

git checkout master
git checkout -b small_pr_two

You can use $ git stash show to list the remaining files in your stash. If you want to apply changes from the stash selectively you can use git checkout stash@{0} -- <your filename> to checkout an individual file from the stash. If you need to see a diff between what’s in the stash and your current branch run: git diff stash@{0} -- <your filename>

Additional Resources

Another approach you might want to try is Stacked PRs by Grayson Koonce: https://graysonkoonce.com/stacked-pull-requests-keeping-github-diffs-small/

I’ve used Stacked PRs a few times but tend to prefer keeping my branching structure shallow if possible so I normally use the approach shown above.

Happy Coding!

-g

We’ll start a sample project named tnsvuefirebasestarter. If you’d like to see the source for the finished project it’s available here:

groksrc/tnsvuefirebasestarter

First start by creating your new project. I’ve just installed the new Vue CLI 3.0 release and haven’t had any trouble:

$ vue init nativescript-vue/vue-cli-template tnsvuefirebasestarter

Once the template initializes your project, change to the directory

$ cd tnsvuefirebasestarter

Now install dependencies with npm. NOTE: do not use yarn. I found that for some reason the hooks directories are not created when using yarn and this prevents the project from compiling correctly.

$ npm i

Next, you’ll need to open the firebase console and download the project files that allow the apps to connect to firebase. If you’re using Android the file named google-services.json and put it in the template/app/App_Resources/Android directory. For iOS download the GoogleService-Info.plist file and place it in template/app/App_Resources/iOS.

Now we’ll install the firebase plugin. Running this command will execute a template that will ask you which firebase services you’d like to enable. NOTE: I had trouble with the Messaging component and was not able to get it to compile or run on Android or iOS. I don’t know if this is an existing issue, but to work around it I chose not to enable it. Also, messaging on iOS in the emulator is known to have issues. You may need to test on a real device.

$ npm i --save nativescript-plugin-firebase

Next we need to switch into the template directory and run npm install there as well.

$ cd template
$ npm i

At this point we’re almost finished. Let’s hook up our src/main.js to firebase. Right beneath the line to import './styles.css' add the following code:

import firebase from ‘nativescript-plugin-firebase’;
firebase.init({
  // Optionally pass in properties for database, authentication and cloud messaging,
  // see their respective docs.
}).then(
 instance => {
   console.log(“firebase.init done”);
 },
 error => {
   console.log(`firebase.init error: ${error}`);
 }
);
Vue.prototype.$firebase = firebase;

Now make sure you run a clean before launch:

$ npm run clean

At this point your project should be ready to go. For android run:

$ npm run watch:android

For iOS run:

$ npm run watch:ios

If everything goes as expected the app should start up and you should see the following in your console:

JS: 'firebase.init done'

I’d like to give special thanks to Jen Looper who worked consecutive weekends with me helping me to figure this out. If you need additional help there’s a #firebase channel in the NativeScript Community Slack where you should be able to reach either one of us.

Also, be sure to check out her two sample projects in case you need other examples:

• jlooper/elocute
• jlooper/picme

P.S. I’m a relative newcomer to mobile development and ran into trouble compiling on iOS. If you run in to trouble compiling your iOS make sure your developer account is hooked up in xcode and check the project for any errors. You can open the xcode output project after the NativeScript build runs at: dist/platforms/ios/dist.xcworkspace

Happy Coding!

-g

I’ve also been getting into Firebase a bit. It’s a great platform for building all kinds of applications, especially if you want to go serverless. I did some digging for examples on how to set up Nuxt.js on Firebase and there were a few things out there, but nothing that I could just clone and go with. Google’s David East has a video that walks through the process of getting started, but I had a little trouble following it. There’s also this issue on the NUXT GitHub issue tracker that was helpful, but didn’t have an example solution.

So I made one! My sample project is a pseudo search engine that demonstrates how you can get started with Nuxt.js on Firebase today. It leverages three features of Firebase: Hosting, Functions and Storage. And it also illustrates how to use the asyncData feature described in Sebastien’s talk.

If you haven’t worked with Nuxt.js or Firebase before this is an easy way to get started with both. Here are the high-level steps you need to take:

• Set up a Firebase account and create a project
• Set up your environment
• Clone the project and initialize Firebase
• Run locally
• Publish & Voilà

Get a Firebase Account and Create a Project

You can do this at https://firebase.google.com. After you’ve signed in with your Google account hit the giant Add Project button and start a new project. Give it a name and hit the Create Project button. Once you‘re on the project dashboard click Storage from the left nav, then click Get Started. This will enable Storage for you and give you a place to upload files. After we clone the project we’re going to drop a results.json file here so that it’s available to query. This will drive the search results screen. Now you’re ready to head over to your terminal.

Environment Setup

First you’ll want to be sure that you’re running Node 8.x or later. Firebase only supports Node 6 right now (es5), but that’s ok. This project uses webpack/babel to transpile for you, so you can ignore the warnings you may see about this in your console. You’ll also want to be sure that you have the Firebase CLI tools installed:

$ npm install -g firebase-tools

Clone and Init Firebase

Now you can clone the project repo. Once you’ve done that you need to hook the code up to your Firebase project. Do that with the following:

$ git clone git@github.com:groksrc/groksrc-search.git
$ firebase init

This will walk you through a series of questions and at the end a .firebaserc file is created for you. This is how the Firebase CLI knows where your backend is.

⚠️ Caution: when you run the init command it will overwrite the firebase.json file. Be sure to discard this change and just keep the .firebaserc file.

As you walk through the firebase init command options select the following:

Step 1:

• Choose only the Hosting option. You can skip the others because this configures the firebase.json file and we already have one in the project.

Step 2:

• Select the project you created above from the list of choices. If you don’t see it, make sure you’re logged in to the correct account. This will be saved in the .firebaserc file.

Step 3:

• Enter dist for the public directory. This will prevent junk files from being created.

Remaining Steps:

• Choose the defaults

Now be sure to reset the firebase.json file. Once that’s complete you need to also need to be sure and install the npm dependencies:

$ yarn install # or npm install

Running Locally

Now you should be able to start the project locally. Use the following command to make sure that everything is running:

$ yarn dev

It should start and you should be able to browse http://localhost:3000. If everything is working as expected you’ll see a search page that looks similar to Google’s homepage. Once it’s up you can start making changes, Hot Module Reload should work too.

Note at this point we’re just running with nuxt via node.js. Firebase hasn’t come into play yet. If we want to test our Firebase functions locally we have to transpile the project. Then we can run it:

$ yarn package-functions
$ firebase serve --only hosting,functions

This will launch the app via a Firebase process, similar to what it would do once you publish. Note that HMR is not available while running via the Firebase CLI.

Publishing

To push your project and see it live you can run the following:

$ yarn push

This script will compile the Google Functions code into a /functions directory and publish it for you. The code in this directory is what Functions will use to perform the server side rendering.

Once the push command is complete the project will be up and you can test it on your live URL that is display in the console. Note: when I was testing these steps I noticed that the push command would fail on occasion for some unspecified reason. Just running the command again seemed to take care of the problem.

Summary

The sample app is set to pull the results.json from the original Firebase project I set up for the demo. In order to make your own results just pop open the file in the root directory, tweak & save, then upload it to the Storage project in your app. Once you’ve done that, click on the uploaded file to expand the details and expand the File Location section. Copy the Download URL from this section. Then in the source code locate results.vue and update the URL in the asyncData method to point to your file. Now save and yarn publish again.

That’s it! At this point you’re off and running with Nuxt.js and Firebase. I hope you’re able to spend a few minutes with these two awesome technologies, it’s definitely a smooth way to build an app and I’ve really enjoyed getting acquainted with them. Until next time!

g

Here’s a new language I’m really excited about: Elixir. Elixir is a higher order functional language with the aesthetics of Ruby. It is derived from the old telecom language, Erlang, and in fact it transpiles down to vanilla Erlang source code which then targets Erlang’s BEAM runtime.

Elixir is a functional language, and one of the easiest and best to get started with if you’re new to functional languages. The idea with functional languages is that functions live inside of modules and modules process data. That’s it. There are no objects to instantiate. You simply transform data from one shape to another shape, always returning something new from your function.

It sounds strange if you’ve never worked without objects before, but I find this approach incredibly refreshing. And if you think about it, it makes total sense for the web because you’re just transforming web requests into web responses. The web’s stateless nature naturally fits a data in and data out request/response paradigm.

Phoenix Framework

The Phoenix Framework is commonly compared to Rails, it’s counterpart in OO land, but Phoenix is actually quite different from Rails in many respects. New developers to both Elixir and Phoenix should proceed with humility and an open mind as problem/solution pairings can vary a good deal from their OO counterparts.

But once you’re up to speed, you should find Phoenix to be a capable, fun development experience with a more advanced toolchain and solution space than you might expect from such a young framework.

I’ve used it now on a few small projects and find it to be approachable, familiar and well documented. In fact, hexdocs and the built in documentation solution Elixir provides is yet another reason I see big things on the horizon for this up-and-comer.

Recommended Reading

I’ve read through the following titles personally and recommend them for getting up to speed with Elixir and Phoenix. The community forums are also active and there’s a positive vibe around the core contributors and the direction the language is taking, so things are looking up.

• Programming Elixir > 1.6
• Programming Phoenix
• Craft GraphQL APIs in Elixir with Absinthe

Demo

Finally, when you’re just getting started with a new language it helps to look at some code. Here’s a quick project I did to demonstrate how you can hook Phoenix to a Postgresql database and render something.

groksrc/tablex

In this case it just renders the names of the tables that are in the database by creating some schema files to get started with. NOTE: It is not recommended to use these schema files to build an app, you’d really do better with focused Contexts instead of fat schemas, but the point is that it gives you something to look at and play with.

Summary

I hope you have a few minutes to sit down and experiment with Elixir. It’s a viable option today and for a certain class of problems it is a fantastic fit. We’ve been using it in production at my current role for some time now and it runs like a champ. Enjoy!

g

The API is Stable

I really like how Evan and the core contributors have defined a nice API and they don’t feel or see the need to overhaul it often. Sure it is changing and improving over time, but it’s not a constant revolutionary change.

me: gives side-eye to webpack 👀

The API is easy to understand

You have in the API exactly what you would expect: A well defined, easy to follow event lifecycle for components that define a series of steps to go through to render some html.

The real beauty of the vue.js approach is the ability to define html and javascript in the same file, but separate the markup from the javascript. It makes the code familiar, easier to read, and to reason about.

Contrast with React the blurring of html, xml and javascript into jsx. The entire learning curve is avoided in vue.js, and we follow the same paradigms that we have traditionally followed. Your view code and model/controller code remain separate and distinct. Simple.

The Style Guide

The Vue.js Style Guide is a fantastic way to define cohesion in the community around best practices and what a cannonical code base should look like.

You may or may not like every rule and suggestion that they define, but they at least contribute to what you should be thinking about and you should have just cause to deviate from them.

By following the conventions, the broader community benefits as we collaborate with a shared understanding of how things should be put together. It increases productivity and reduces the number of things to actually think about as you implement your project requirements.

vue-router and vuex

It’s unfortunate (imho) that React doesn’t take a more pronounced approach on what is recommended when dealing with routing or storage. Though clearly react-redux and react-router are some common go-tos, there are many, many other options. And while React works well together with these libraries, we’re told up front that the relationship is not explicit. In fact, the first line of the Redux docs state that “Redux has no relation to React”.

With vue-router and vuex we are given the recommended path, which in cases of frameworks like this, happens to be exceedingly helpful. It reduces the amount of discovery necessary and leads you to more consistent implementations across projects. In a large environment I find this point to be expecially compelling.

Summary

I’m sorry for any React fans I may have rubbed the wrong way. This wasn’t to bash React as much as it was to talk up the benefits of Vue.js and React is obviously a primary basis for comparison. React is clearly a popular choice, and valuable technology. But I hope you have the chance to spend some time with Vue.js. It’s a great framework for small and large projects. It has my full throated endorsement.

g

I’ve worked in a lot of different engineering environments over the course of my career and one thing that always comes up as the team grows is how to handle documentation. At a certain point you just can’t scale effectively without it.

So then the question automatically becomes, “Who is going to write it?” In some places I’ve worked this question goes unanswered. That’s unfortunate because now the ticketing system winds up as the default documentation center. This is problematic for a number of reasons, but more importantly the team suffers as a result.

Technical Writers

Often the suggestion is made to hire a technical writer. “Engineering time is valuable so why waste it on mundane tasks” is a common refrain I’ve heard. Someone with experience writing good documentation will surely be able to produce high quality documentation that normal human beings can read. Right? Not so fast..

Technical writers can most certainly produce quality content. That’s not an issue. But experience tells us that the content they produce can vary significantly based on how they understand the systems they are documenting and who is available to provide color commentary about what is going on.

In many cases having good documentation is not simply about users being able to access a set of instructions about how to use the software. The best documentation covers things like special conditions, potential problem areas and remediations, and background information on why the system is designed in the way that it is.

And how could a Technical Writer ever get any of that information by only looking at the screens of the software? More often than not, the software engineers are the only people in the room who know what is really going on under the hood.

Aside from that, if you think about the responsibilities of a Technical Writer we realize that they cover a lot more than just producing standard documentation for the system. They also need to format, publish, and version the documentation which can be a daunting task in and of itself.

Why Software Engineers Should Write Documentation

In an ideal world the Technical Writer on your team is not the author. They are the editor and the engineers are authors. Technical Writers can help guide us to publication, much like would happen when writing a book. But as software engineers we have the most in-depth knowledge about the systems we develop and often times can do the best job of explaining the details about how things actually work.

But wait! I can already hear some of you grumbling about how documentation is boring or that nobody reads it and that it’s a waste of time. Well, if you’ve made it this far then why not become part of the solution?

I posit that software engineers are authors irrespective of what we write, but instead of limiting ourselves to writing code we should open ourselves to authoring all types of documents. The best engineers I know are also very keen on this point. If you’ve mastered writing code and tests, documentation is your next challenge.

How To Write Good Documentation In 5 Minutes Or Less

It’s more easy than you realize to write good documentation. You do it every day, you just don’t recognize it as such. And the documentation you do write remains “stuck” where you wrote it: in the code. Here are 3 easy steps to break that documentation log jam.

1. Start a docs folder

The docs folder can live in your project repo or somewhere else. Just make sure it’s easy for everyone else to get to it. Inside the folder I recommend vanilla markdown unless it’s hosted and provides its own formatting (e.g. Confluence). You could even use Jekyll if you wanted. The key is that there’s low friction to getting into the documentation and working with it.

2. Start An Outline

When you’re ready to start a new page of documentation create an empty file and start with a title and some headings. Here’s an example of how I did this very thing when writing this article:

Software Engineers Are Authors

## Background
## Technical Writers
## How To Write Good Documentation

If you’ve ever used GitHub’s hub utility, this should be familiar. Like when you use $ hub pull-request, the first line of the document is the title, followed by an empty line. Anything after that is the body content. In the body use markdown headings an write an outline that covers just the main topics of what this feature does. The names of your public methods are good starting points.

3. Start A Loop

Any time you’re stuck waiting on a task (installers, downloads, jobs, builds) is a good time to loop into the docs and add flesh to your outline. When your task is finished, context switch out. Even if you just note the thoughts you’re having as you’re working, that’s good to get down. It’s this simple process where you consistently loop through the docs that really makes the difference because you’re now slowly adding to a critical component of the software that is often overlooked. If you’re stuck waiting on an operation, go async yourself. It will make you more efficient and your Technical Writer will thank you.

You + Your Technical Writer = Jimmy & Justin #winning

If you’ve done all of this, now your Technical Writer has awesome source material for coloring the documentation they create. If you don’t have a Technical Writer yet you’ll be prepared with some basic content for when they arrive. Either way it’s a win/win.

ProTip: For When You Don’t Like Long-form Entry

Speach to text is actually pretty good now. Using a dictation app can save loads of typing and speaking is typically faster than typing anyway. If you have a lot of content but don’t want to bother typing it all out give this a try. You might be surprised at how well it works.

Summary

You just read a lot about documentation. Congratulations! Here’s your prize.

g