add more documentation

README.md

@@ -14,12 +14,33 @@ Otherworld creates a persistent Docker container running your choice of GNU/Linu
 ### Remove the container
 `otherworld --rm`
 
+## Arguments
+These are arguments that go between `otherworld` and the command.
+
+### --container=<container>
+Name to assign to container (default: `otherworld_$USER`)
+
+### --image=<image>
+Image to create the container with (default: `debian:stable`)
+
+### --sudo
+Runs command as root, instead of current user.
+
+### --rm
+Removes the specified container.
+
+### --build=<path>
+Path to build context to build the image from. This overrides `--image`/`OW_IMAGE`.
+
+### --volume=<volume>
+Volume to map to the container. `~` is expanded automatically. If the directory exists in the user's home directory it will be created to ensure it has the correct ownership and permissions.
+
 ## Environment variables
 ### OW_IMAGE
 Image to create the container with (default: `debian:stable`)
 
 ### OW_CONTAINER
-Name to assign to container (default: `overworld_$USER`)
+Name to assign to container (default: `otherworld_$USER`)
 
 ## License
 [GNU GPL v3](https://www.gnu.org/licenses/gpl-3.0.en.html) or later

otherworld

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-from subprocess import call, check_output
+from subprocess import call, check_call, check_output
 from time import sleep
 import os
 import sys
@@ -58,6 +58,19 @@ def docker_exec (container, command, user):
 def docker_rm (container):
     call(["docker", "rm", "-f", container])
 
+def docker_build (build_path, options, image_name):
+    check_call(["docker", "build"] + options + ["-t", image_name, build_path])
+    return image_name
+
+def docker_pull (image_name):
+    check_call(["docker", "pull", image_name])
+
+def resolve_build_path (build_path):
+    if build_path is not None and build_path.startswith("~/"):
+        build_path = f"{os.environ['HOME']}/{build_path[1:]}"
+
+    return build_path
+
 def expand_user_volumes (volumes):
     outer_home = os.environ["HOME"]
     inner_home = outer_home
@@ -84,10 +97,12 @@ def expand_user_volumes (volumes):
 user = os.environ["USER"]
 image_name = os.environ.get("OW_IMAGE", IMAGE_NAME)
 container_name = os.environ.get("OW_CONTAINER", f"{CONTAINER_NAME}_{user}")
+build_path = None
 
 command = sys.argv[1:]
 command_user = user
 user_volumes = USER_VOLUMES
+pull = False
 
 quiet = False
 while len(command) > 0:
@@ -109,9 +124,15 @@ while len(command) > 0:
     elif arg.startswith("--image="):
         image_name = arg[len("--image="):]
         command = command[1:]
+    elif arg.startswith("--build="):
+        build_path = arg[len("--build="):]
+        command = command[1:]
     elif arg.startswith("--volume="):
         user_volumes.append(arg[len("--volume="):])
         command = command[1:]
+    elif arg == "--pull":
+        command = command[1:]
+        pull = True
     else:
         break
 
@@ -122,6 +143,12 @@ container = None
 try:
     container = docker_inspect(container_name)[0]
 except Exception:
+    build_path = resolve_build_path(build_path)
+    if build_path is not None:
+        image_name = docker_build(build_path, ["--pull"] if pull else [], f"image_{container_name}")
+    elif pull:
+        docker_pull(image_name)
+
     if not quiet:
         print(f">> Creating container: {container_name} (using image: {image_name})")
     docker_create(

test_image/Dockerfile

@@ -0,0 +1,2 @@
+FROM debian:stable
+RUN echo 'test' > /root/test