WIP: Readme revamp

[kekoav]

Let's give the README a much-needed refresh. Let's collaborate on this to make img easier to use, and reduce the time for newcomers to get started.

Some of my goals here:

• Restructure and organize the text into a more logical flow and hierarchy.
• Clarify goals section. Considered non-goals as well, but left it at goals.
• Emphasize Docker and Kubernetes usage since that is likely the biggest draw for using img in a containerized environment.
• Explain how img can be used for Mac and Windows users.
• Organize Linux installation instructions... still feel like this dominates a little too much with all the packages, etc. May want to pull this out into an INSTALLING.md file.
• Trim out excess text from the CLI Usage section, for less scrolling.
• Added some details for how to build and contribute to img. Could go to a CONTRIBUTING.md file instead.
• General editing for grammar, punctuation, style, etc.

Resolves #251 .

Table of Contents

I'm experimenting with a depth of 3 to limit noise on the TOC.

markdown-toc --maxdepth 3 -i README.md

TODO

The following areas I still think are weak. I'm perusing common issues and looking for user gaps that could make adoption of img easier.

• [ ] Better introductory level explanation to "why img?"...
• [ ] More/better visuals to demonstrate and explain.
• [ ] Running in common CI/CD systems: GitLab CI, Jenkins, etc.
• [ ] How to include img in Dockerfiles with various bases... alpine, stretch, buster, xenial, etc.
• [ ] Put details into separate files: CLI, Internal details, Contributing, etc. These can all be split out to allow the README to focus on getting started and project "orientation".

[frezbo]

@kekoav FYI, I was able to get img working on fedora 31 with cgroupsv2 just by creating a symlink for runc pointing to crun, which I did not expect at all to work. Not sure if it's worth mentioning in README

[kekoav]

@kekoav FYI, I was able to get img working on fedora 31 with cgroupsv2 just by creating a symlink for runc pointing to crun, which I did not expect at all to work. Not sure if it's worth mentioning in README

@frezbo That is very nice, does that change the security requirements necessary? Can we run with less privileges?

[frezbo]

I was running as a normal user in a fedora 31 VM.

[codecov-io]

Codecov Report

Merging #287 into master will not change coverage. The diff coverage is n/a.

@@          Coverage Diff           @@
##           master    #287   +/-   ##
======================================
  Coverage    0.00%   0.00%           
======================================
  Files          16      16           
  Lines        1006    1006           
======================================
  Misses       1006    1006           

---

Continue to review full report at Codecov.

Legend - Click here to learn more Δ = absolute <relative> (impact), ø = not affected, ? = missing data Powered by Codecov. Last update 89fb42e...49519e9. Read the comment docs.

[ChrisTomAlx]

docker run --rm -it --name img --volume "$(pwd):/home/user/src:ro" --workdir /home/user/src --volume "${HOME}/.docker:/root/.docker:ro" --security-opt seccomp=unconfined --security-opt apparmor=unconfined --security-opt systempaths=unconfined --entrypoint sh r.j3ss.co/img

This is exactly how I had to run it to make it work on docker toolbox for windows.. Just dropping it here in case it helps someone. As you can see I added the double quotes for the first --volume

[kekoav]

This is exactly how I had to run it to make it work on docker toolbox for windows.. Just dropping it here in case it helps someone. As you can see I added the double quotes for the first --volume

@ChrisTomAlx Updated to add quotes on both.