dockbox is a useful CLI tool for trying out code from remote repositories. It allows you to to try out code quickly and easily without compromising your own system, and easily organize your workspace. Plus, it makes it very easy to delete the dependencies and other side effects that result from running the code.
All you need is Docker installed on your system, and let dockbox do the rest.
dockbox currently requires Docker to run. Please visit https://docs.docker.com/get-started/ for installation instructions.
Install the latest release for your OS/architecture. If the binary is in a non-standard location, please remember to update your PATH variable accordingly.
If you have homebrew installed on your system:
brew tap dockboxhq/cli https://github.com/dockboxhq/clibrew install dockbox
If installing dockbox from the source, clone the repository and run go install in the root directory to install dockbox on your system.
After installing dockbox, run dockbox create <url> to create a dockbox from a URL. The code repository that you choose does not need to have a Dockerfile to run, but if it does, dockbox will use it to create a dockbox. Otherwise, it will generate one for you.
Once you are done with the dockbox, clean up your resources with dockbox clean <dockbox name> which will clean up all side-effects/resources associated with the code you just installed. The dockbox name is usually the repository name that you cloned from, but if you want to be sure, you can use dockbox list to list out all the dockboxes installed on your system.
To summarize, there are 5 easy steps to getting started:
- Install
dockbox dockbox create <url>dockbox clean <dockbox name>
For a full list of available commands, dockbox help
-> % dockbox help
Usage: dockbox [OPTIONS] COMMAND
Manage workspaces and dependencies with ease in an isolated, secure environment.
To get started with dockbox, try entering:
dockbox create <url>
Usage:
dockbox [command]
Available Commands:
clean Removes a dockbox from your machine
create Creates a dockbox from a URL, file or git URL
enter Enters into a dockbox in a given directory
help Help about any command
list List all your dockboxes on your system
tree Shows a tree of dockbox image histories
Flags:
--config string config file (default is $HOME/.dockbox.yaml)
-h, --help help for dockbox
Use "dockbox [command] --help" for more information about a command.
Easily clean up relevant images and side effects with the dockbox clean command
Currently, the algorithm for generating a Dockerfile is simple. We walk the file tree of the project, counting the number of files associated with each programming language. Then, we ask user which language should we generate a Dockerfile for, given the most frequent files found in the project.
In the future, dockbox will compose a tree in which we can store more information about modules, and resolve multi-module projects better.
Internally, dockbox constructs a forest of images in order to construct a deletion plan for the images installed on a user's system. This is to avoid both dependent child images errors, and also associated container errors. To construct such a forest, we take each image given by Docker's List images, and run a history command using the image IDs. This approach is faster than using the Image Inspect API call (which only returns the parent image) since history only needs to be called on each of the leaf images.
Here is the description of the algorithm for deleting a node from the forest:
Algorithm:
1. Find image ID of target Node
2. a) If target node has children, then for each child:
i) Skip the child if it has already been previously visited
ii) Perform a postorder search on the tree rooted at that child, adding entries to the deletion queue.
If any tagged images that are leaves were visited, confirm with user before adding the entries to the deletion queue.
b) Else
i) if image is tagged, then confirm user with before adding to deletion queue
ii) Else, add to deletion queue immediately
3. a) If the user has aborted the search by responding no to deletion of node, or if we have reached a node in which the parent is null,
then we are done.
b) Otherwise, we visit the parent node and perform steps 2-3 again.
4. Delete the images in the deletion queue.
dockbox uses the following data structures to aid in executing the algorithm efficiently:
- map from Image ID to ImageNode
- queue of Image IDs to represent deletion plan
- each node in the forest has both a parent pointer, and an array of children
This project is still a work in progress! We will continue to add more features as we explore more use cases. If you have ideas on possible additions of features you would like to see added to dockbox, reach out at srihari.vishnu@gmail.com, or better yet, open a pull request!
Features in Progress:
- Allowing URLs other than git repositories
- Adding better customizability for images and commands
- Multi-module support to analyze a file tree and give possible groupings of a possible project structure
- This is useful when say having a backend and a frontend in different folders in the same repository
- Add ability to define custom rules for Dockerfile generation
There is still a lot of work to do on this project! All help is welcome!
To get started contributing, please ensure that go and docker installed are installed on your system. After, run the following steps to build a binary and run it:
cd dockboxgo build -v ./...dockbox help
The repository follows the standard structure of a Cobra Go CLI project. For questions and inquiries, again feel free to reach out at srihari.vishnu@gmail.com.
If there are no open issues to work on, here are some ideas on how you can contribute:
- Add documentation
- Create tests
- Add more options to commands to give more granular control
- Implement features for Roadmap
To run tests, run go test -v in the cmd directory. To update the golden files, run go test -update.
This project is licensed under the Apache 2.0 License.