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.

[lcbm]

Hey @kekoav! Could double-check on this section, please? I believe I ran into a a mistake on line 228:

- $ git clone https://aur.archlinux.org/packages/img.git
+ $ git clone https://aur.archlinux.org/img.git

The current link gives me this:

λ git clone https://aur.archlinux.org/packages/img.git
Cloning into 'img'...
fatal: repository 'https://aur.archlinux.org/packages/img.git/' not found

The suggested one (from aur.archlinux.org) works fine:

λ git clone https://aur.archlinux.org/img.git
Cloning into 'img'...
remote: Enumerating objects: 13, done.
remote: Counting objects: 100% (13/13), done.
remote: Compressing objects: 100% (11/11), done.
remote: Total 13 (delta 1), reused 13 (delta 1), pack-reused 0
Unpacking objects: 100% (13/13), 2.98 KiB | 2.98 MiB/s, done.

In case you think this fix is out of the scope of your PR, LMK and I'll gladly open one with the fix 😄

BTW, great docs! Looking forward to the section with examples for GitLab CI and How to include img in Dockerfiles with various bases..., as the current documentation for that is lacking info -- these sections would help my team and I a ton! I'm more than willing to help with that in case you need 🎉