inklewriter

Important note: the technique described here doesn’t work so far on Raspberry Pi. But we’re working on it!

We’re very happy to run inklewriter as a service for everyone. As a user, It’s really great to just log in the service and write stories without having to handle all the hard and boring hosting aspects.

And Inklewriter is just so easy to use that numerous teachers like to use it for educational purpose. Which is absolutely awesome. Watching a bunch of 10 years old pull crazy interactive out of thin air should really be on your TOP 100 things to do in life.

But it apppears that, sometimes, an online service is not the best option. Especially for teachers.

For legitimate security reasons, some schools limit access to the Internet, and that’s why we want to tell you how to run Inklewriter by yourself.

Inklewriter is free to run on any laptop or computer

If you think we’re kidding, we’re not.

Since Inkle Studios freed the code, Inklewriter is free software, meaning that you can download it, study it, modify it and even distribute it.

Now if you’ve been on the Internet for long enough , you know there’s a catch.

Free to install, not always easy to install.

Which is somehow true in the case of Inklewriter, as installation has a certain level of difficulty.

So here are the learning objectives we’ll detail in this blog post.

1. How to run Docker on Windows
2. How to run Docker on Linux
3. How to run Inklewriter using a compose file
4. How to access the Inklewriter service from other computers / tablets / etc.

1. How to run Docker on Windows

To distribute Inklewriter, we use a very common technology called «Docker».

Docker is really cool, because once you download a Docker Image like Inklewriter, you don’t have to install anything anymore: your download contains all the necessary code and configurations, ready to run.

Yet there’s a catch. Docker doesn’t play so well on Windows. You can try to install Docker Desktop using the official documentation.

If it installs alright, good for you! Keep reading the 3rd objective of the article, the operation will be similar on Windows and Linux.

2. How to run Docker on Linux

Generally the main problem is “How to run Linux”.

The solution is actually pretty simple. You need to install it.

You have two choices :

1. Installing on the main drive
2. Installing on a USB Key

2.1 Installing Linux on the main drive

Linux is easier on the main disk of a computer , but it requires that you devolve a laptop (for example) entirely to the Linux system, unless you use Dual Boot if you feel like it.

That’s your option? Great. Head to the How To Install page of Ubuntu and follow their instructions.

Basically, you will be instructed how to copy an ISO file on a USB key, boot on this key and select the computer’s disk as the target of installation.

2.2 Installing Linux on an USB drive

It is a bit more complex, as it requires more knowledge including tweaking the BIOS menu of the computer.

Yet the advantage is that you can keep the existing OS (presumably Windows) on the computer without altering it.

Now the weird thing is that you will need two USB keys.

You will prepare the first key as explained in the above paragraph, but you will not select the hard drive or SSD of the computer as the target of installation! It is the second key that you will target. And once the installation is done, this second key will be bootable.

Actually, you could just use the “Live USB” capacity of your Ubuntu key, but everything you install will be lost on reset, including your stories. That’s why installing a real system is necessary.

Here is an article that explains the process. It’s not *that* hard.

Now you will need to install Docker on the Linux computer.

Docker has help pages for that, for Ubuntu or for LinuxMint.

It’s not hard, but you need to run a console / terminal -you know that thing where you type text and feel like a hacker- and request commands like

sudo apt update
sudo apt install docker.io

3. How to run Inklewriter using a compose file

Now we’re getting there!

Once you’ve installed Docker, you’re almost done, as there are only two things to do.

3.1 Download the Inklewriter docker-compose.yml file

The file can be found here and its content goes like this.

version: '2'

volumes:
  inkledb:
    external: false

services:

  db:
    env_file: .env
    image: postgres
    volumes:
      - inkledb:/opt
      
  app:
    env_file: .env
    image: albancrommer/inklewriter:latest
    ports:
      - "3000:3000"
    depends_on:
      - db
  

We recommand that you create a new folder and copy that file in it using the name docker-compose.yml and not any other one, otherwise docker will not recognize it by default.

3.2 Run the docker-compose command

Use a terminal and navigate to the folder containing the docker-compose.yml file. If you’re using Docker on Windows, the process is the same, but you need to use the Windows Terminal or PowerShell.

The command to run in your terminal is :

docker-compose up

You will need to have access to the Internet at this point (and not later) because the computer will download images to run the service: an Inklewriter image with the code and a Postgres image for the database.

Once it’s done and you see lines with timestamps and odd messages, the service should have started.

You can use your browser to access it on http://localhost:3000

Et voilà ! You just see the Inklewriter home page! Of course, it won’t be sending any email for password retrieval and things like that, but it should be enough for a teacher to work with her students.

How to access the Inklewriter service from other computers / tablets / etc.

Now, you’ve got Inklewriter running on a single computer. How do your students access it from other computers?

Of course, it is not a problem if you request them to use the computer on which the service is running, or if you have enough time and laptops to install it on all of them.

If you need to connect the students to the service running on the computer, it is necessary for them to be on the same local network.

So you and your students will probably need to share a WIFI network so that their computers can “see” yours.

Your students will need to know the IP of your computer to connect to it. Here’s how to find it.

On Windows

1. Start > Settings > Network & internet > Wi-Fi and then select the Wi-Fi network you’re connected to. Read the IPv4 under Properties
2. Using the Command Prompt or Powershell, type ipconfig

On Linux, using the command line

ip -br -c a

will output something like this

lo               UNKNOWN        127.0.0.1/8 ::1/128 
wlo1             UP             192.168.1.105/24 fe80::c2a5:22df:6aea:ea3f/64 

The IP address you’re searching is something like 192.168.1.105 but this is just an example, and it might depend on your local network.

Now that you have your computer’s IP Address, it’s time for others to connect to it

The URL they will use is simply the IP address with the special «port» 3000 attached to it. Following our previous Linux example, it would be:

http://192.168.1.105:3000

If everything goes fine, your students should see the Inklewriter interface.

Hurray! Excitement! Fanfare! Time for new interactive stories!