↓Skip to main content

Running IO with Docker

579 words·3 mins
Agent IO
Author
Agent IO
Table of Contents

IO is distributed as a Docker image
#

During the private preview, IO is distributed on Docker Hub as agentio/io. The IO image is based on envoyproxy/envoy with two additions:

  • The IO binary is copied to /usr/local/bin/io, where it becomes the entry point for the container.
  • An /io directory is added and IO runs in this directory. Typically, this directory would be mapped to a volume outside the container.

Here’s the relevant section of the IO Dockerfile:

FROM envoyproxy/envoy:v1.33-latest
COPY --from=builder /app/io /usr/local/bin/io
RUN mkdir /io
WORKDIR /io
ENTRYPOINT ["/usr/local/bin/io"]
CMD ["io"]

Run IO interactively using Docker
#

To run IO interactively, save the following in a file named IO.sh and make it executable:

#!/bin/sh
#
# Interactively run IO in a docker container.
# * The TERM variable allows colors to be displayed correctly.
# * Host networking allows IO and Envoy to bind to local ports.
# * The volume option allows IO to run in the current directory.
#
docker run -ti -e "TERM=$TERM" \
  --network host \
  --volume $(pwd):/io \
  agentio/io -i $@

Run IO from your terminal with ./IO.sh [options], where [options] are any additional options that you want to add.

Run IO as a daemon using Docker
#

To run IO as a background process, save the following in a file named IO-background.sh and make it executable:

#!/bin/sh
#
# Run IO in a docker container.
# * The detach option runs the container in the background.
# * Host networking allows IO and Envoy to bind to local ports.
# * The volume option allows IO to run in the current directory.
#
docker run --detach \
  --network host \
  --volume $(pwd):/io \
  agentio/io $@

Run IO from your terminal with ./IO-background.sh [options], where [options] are any additional options that you want to add.

Stop your backgrounded IO
#

If you’re running IO in the background with Docker, you can see your process with docker ps:

$ docker ps
CONTAINER ID   IMAGE        COMMAND                  CREATED          STATUS          PORTS     NAMES
1583170b4d3e   agentio/io   "/usr/local/bin/io io"   28 minutes ago   Up 28 minutes             mystifying_kilby

Then you can stop your IO with docker kill.

$ docker kill 1583
1583

⚠️ Files created in Docker are owned by root
#

When you run IO for the first time, it creates a SQLite database in a file named io.db and several log files. Because IO runs inside docker as root, these files are initially owned by root. You can fix that by using chown and chgrp to change the ownership of these files. Just run this in the directory where you are running IO:

chown -R $USER .
chgrp -R $USER .

⚠️ Docker can’t see outside your run directory
#

If you try to read files outside your current directory, IO won’t be able to see them. For example, using the script above:

$ ./IO.sh -c ~/license.hcl
Error: open /home/tim/license.hcl: no such file or directory
Usage:
  io [flags]
...

This file is readable in my shell, but it’s unreadable in Docker because only my current directory is mapped to IO’s Docker volume. It’s an inconvenience but also a security feature.

⚠️ IO should be run with Host Networking
#

Note that we’re running IO with host networking. This allows IO to directly use ports on the host system, which usually include ports 80 and 443 for HTTP/HTTPS, port 8022 for SSH/SFTP control of IO, and all of the other ports that you specify when you configure IO callers and senders.