otherworld/README.md

# Otherworld
Otherworld creates a persistent Docker container running your choice of GNU/Linux distribution, with a matching user account (no need to run everything as root) and with x11 and PulseAudio mappings. The container is created the first time you run otherworld and sticks around until you dispose of it manually.

## Usage
### Run command as user
`otherworld <command> <arguments>`

### Run command as root
`otherworld --sudo <command> <arguments>`

### Run command without printing anything else
`otherworld --quiet <command> <arguments>`

### Remove the container
`otherworld --rm`

## Arguments
These are arguments that go between `otherworld` and the command.

### Creation Options

#### --image=<image>
Image to create the container with (default: `image_$CONTAINER_NAME`, or `debian:stable` if that image does not exist)

#### --build=<path>
Path to build context to build the image from. This overrides `--image`/`OW_IMAGE`. The resulting image is named `image_$CONTAINER_NAME`

#### --volume=<volume>
A volume to mount in 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.

#### --container=<container>
Name to assign to container (default: `otherworld_$USER`)

### Command Options
#### --env=<key>=<value>
Set the environment variable `key` to `value` in the command. **Note that this does not set environment variables in the container itself**.

#### --sudo
Runs command as root, instead of current user.

#### --cd/--cd=<directory>
Runs command in the specified directory, or current directory by default. If the container is being created, specified directory is added to list of volumes to mount. Otherwise, if the specified directory does not exist in the container, an error is raised.

### Container manipulation commands
#### --rm
Removes the otherworld container.

#### --rmi
Removes image generated by the `otherworld` script (`image_$CONTAINER_NAME`)

#### --commit
Commits the container to an image named `image_$CONTAINER_NAME`.

## Environment variables
### OW_IMAGE
Image to create the container with (default: `debian:stable`)

### OW_CONTAINER
Name to assign to container (default: `otherworld_$USER`)

## License
[GNU GPL v3](https://www.gnu.org/licenses/gpl-3.0.en.html) or later
initial commit 2020-03-27 00:17:20 -05:00			`# Otherworld`
			`Otherworld creates a persistent Docker container running your choice of GNU/Linux distribution, with a matching user account (no need to run everything as root) and with x11 and PulseAudio mappings. The container is created the first time you run otherworld and sticks around until you dispose of it manually.`

			`## Usage`
			`### Run command as user`
			`otherworld <command> <arguments>`

			`### Run command as root`
			`otherworld --sudo <command> <arguments>`

			`### Run command without printing anything else`
			`otherworld --quiet <command> <arguments>`

			`### Remove the container`
			`otherworld --rm`

add more documentation 2020-03-27 21:50:13 -05:00			`## Arguments`
			These are arguments that go between `otherworld` and the command.

Add --cd=<directory> option to run command in specified directory, or --cd option to run command in the current directory. If the container is being created, this directory is added to the list of directories to mount. Otherwise, if the directory does not exist in the container, an error is raised and the command fails to run. 2020-09-27 19:39:14 -05:00			`### Creation Options`
add more documentation 2020-03-27 21:50:13 -05:00
Add --cd=<directory> option to run command in specified directory, or --cd option to run command in the current directory. If the container is being created, this directory is added to the list of directories to mount. Otherwise, if the directory does not exist in the container, an error is raised and the command fails to run. 2020-09-27 19:39:14 -05:00			`#### --image=<image>`
Make default image name `image_{CONTAINER_NAME}`, and use `debian:stable` as fallback. 2020-08-20 02:37:44 -05:00			Image to create the container with (default: `image_$CONTAINER_NAME`, or `debian:stable` if that image does not exist)
add more documentation 2020-03-27 21:50:13 -05:00
Add --cd=<directory> option to run command in specified directory, or --cd option to run command in the current directory. If the container is being created, this directory is added to the list of directories to mount. Otherwise, if the directory does not exist in the container, an error is raised and the command fails to run. 2020-09-27 19:39:14 -05:00			`#### --build=<path>`
			Path to build context to build the image from. This overrides `--image`/`OW_IMAGE`. The resulting image is named `image_$CONTAINER_NAME`
add more documentation 2020-03-27 21:50:13 -05:00
Add --cd=<directory> option to run command in specified directory, or --cd option to run command in the current directory. If the container is being created, this directory is added to the list of directories to mount. Otherwise, if the directory does not exist in the container, an error is raised and the command fails to run. 2020-09-27 19:39:14 -05:00			`#### --volume=<volume>`
			A volume to mount in 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.
add more documentation 2020-03-27 21:50:13 -05:00
Add --cd=<directory> option to run command in specified directory, or --cd option to run command in the current directory. If the container is being created, this directory is added to the list of directories to mount. Otherwise, if the directory does not exist in the container, an error is raised and the command fails to run. 2020-09-27 19:39:14 -05:00			`#### --container=<container>`
			Name to assign to container (default: `otherworld_$USER`)
Add --rmi command that removes the generated image. 2020-08-20 02:49:34 -05:00
Add --cd=<directory> option to run command in specified directory, or --cd option to run command in the current directory. If the container is being created, this directory is added to the list of directories to mount. Otherwise, if the directory does not exist in the container, an error is raised and the command fails to run. 2020-09-27 19:39:14 -05:00			`### Command Options`
			`#### --env=<key>=<value>`
			Set the environment variable `key` to `value` in the command. Note that this does not set environment variables in the container itself.
Add ability to commit the otherworld container to an image. The image is named the same as in --build option. Also add an --image option (without argument) that uses this image. Not documented because I'm not sure I like this interface. 2020-08-19 02:45:38 -05:00
Add --cd=<directory> option to run command in specified directory, or --cd option to run command in the current directory. If the container is being created, this directory is added to the list of directories to mount. Otherwise, if the directory does not exist in the container, an error is raised and the command fails to run. 2020-09-27 19:39:14 -05:00			`#### --sudo`
			`Runs command as root, instead of current user.`
add more documentation 2020-03-27 21:50:13 -05:00
Add --cd=<directory> option to run command in specified directory, or --cd option to run command in the current directory. If the container is being created, this directory is added to the list of directories to mount. Otherwise, if the directory does not exist in the container, an error is raised and the command fails to run. 2020-09-27 19:39:14 -05:00			`#### --cd/--cd=<directory>`
			`Runs command in the specified directory, or current directory by default. If the container is being created, specified directory is added to list of volumes to mount. Otherwise, if the specified directory does not exist in the container, an error is raised.`
add more documentation 2020-03-27 21:50:13 -05:00
Add --cd=<directory> option to run command in specified directory, or --cd option to run command in the current directory. If the container is being created, this directory is added to the list of directories to mount. Otherwise, if the directory does not exist in the container, an error is raised and the command fails to run. 2020-09-27 19:39:14 -05:00			`### Container manipulation commands`
			`#### --rm`
			`Removes the otherworld container.`

			`#### --rmi`
			Removes image generated by the `otherworld` script (`image_$CONTAINER_NAME`)

			`#### --commit`
			Commits the container to an image named `image_$CONTAINER_NAME`.
Add --env option that sets environment variables in the launched command (not in the container) 2020-08-19 02:48:47 -05:00
initial commit 2020-03-27 00:17:20 -05:00			`## Environment variables`
			`### OW_IMAGE`
			Image to create the container with (default: `debian:stable`)

			`### OW_CONTAINER`
add more documentation 2020-03-27 21:50:13 -05:00			Name to assign to container (default: `otherworld_$USER`)
initial commit 2020-03-27 00:17:20 -05:00
			`## License`
			`[GNU GPL v3](https://www.gnu.org/licenses/gpl-3.0.en.html) or later`