Improve container configuration and documentation

Author: richcarl

.devcontainer/Dockerfile

@@ -2,6 +2,9 @@ FROM erlang:27
 
 ENV DEBIAN_FRONTEND=noninteractive
 
+# Create a default user for the devcontainer
+RUN useradd -ms /bin/bash builder
+
 # Install dependencies
 RUN apt-get update && apt-get install -y \
     git \
@@ -16,24 +19,32 @@ RUN apt-get update && apt-get install -y \
     ruby \
     ruby-dev \
     asciidoctor \
+    default-jre \
+    graphviz \
     && apt-get clean
 
+# Additional Ruby packages
+RUN gem install asciidoctor-pdf asciidoctor-diagram rouge
+
 # Install rebar3
 RUN git clone https://github.com/erlang/rebar3.git && \
     cd rebar3 && \
     ./bootstrap && \
     ./rebar3 local install
 
-# Set environment variable for Erlang shell history
-ENV ERL_AFLAGS "-kernel shell_history enabled"
+# Set Erlang flags for unicode text and shell history
+ENV ERL_AFLAGS "+pc unicode -kernel shell_history enabled"
 
 # Initialize PostgreSQL database for examples
 USER postgres
 RUN /etc/init.d/postgresql start && \
     psql --command "CREATE USER myuser WITH SUPERUSER PASSWORD 'mypassword';" && \
     createdb -O myuser mydb
 
-USER root
+USER builder
+
+# stop git from complaining
+RUN git config --global --add safe.directory /workspaces/theBeamBook
 
 # Set the default command to start PostgreSQL and keep the container running
-CMD service postgresql start && tail -f /var/lib/postgresql/data/logfile
+CMD service postgresql start && tail -f /var/lib/postgresql/data/logfile

.devcontainer/devcontainer.json

@@ -16,15 +16,14 @@
         "ms-vscode.cpptools-extension-pack",
         "ms-vscode.cpptools-themes",
         "ms-vscode.makefile-tools",
-        "pgourlain.erlang",
-        "rebornix.ruby",
+        "erlang-language-platform.erlang-language-platform",
         "twxs.cmake",
-        "wingrunr21.vscode-ruby",
+        "editorconfig.editorconfig",
+        "Shopify.ruby-lsp"
       ]
     },
     "settings": {
       "terminal.integrated.shell.linux": "/bin/bash"
     }
-  },
-  "postCreateCommand": ". /workspace/venv/bin/activate && pip install -r requirements.txt"
+  }
 }

Makefile

@@ -1,16 +1,18 @@
 ASSET_CHAPTERS = $(shell find chapters -type f)
 
-.PHONY: docker
+.PHONY: all pdf html docker docker-build clean serve
 
-all: chapters/contributors.txt beam-book.pdf index.html
+all: pdf html
+
+pdf: beam-book.pdf
 
 chapters/contributors.txt: .git
 	git --no-pager log | git --no-pager shortlog -s -n | awk '{$$1=""}1' | grep -v "Your Name" > $@
 
 beam-book.pdf:  chapters/opcodes_doc.asciidoc book.asciidoc chapters/contributors.txt $(ASSET_CHAPTERS)
 	asciidoctor-pdf  -r ./style/custom-pdf-converter.rb -r asciidoctor-diagram -r ./style/custom-admonition-block.rb  -a config=./style/ditaa.cfg --doctype=book -a pdf-style=./style/pdf-theme.yml book.asciidoc -o $@
 
-index.html: $(ASSET_CHAPTERS)
+html: chapters/contributors.txt $(ASSET_CHAPTERS)
 	cp -r images site
 	asciidoctor -r asciidoctor-diagram  -r ./style/custom-admonition-block.rb -a config=style/ditaa.cfg --backend=html5 --doctype=book -o site/index.html book.asciidoc --trace
 	rsync -R code/*/*.png site
@@ -27,8 +29,8 @@ genop.tab:
 
 clean:
 	find site -type f -name '.[^gitignore]*' -delete
-	rm -rfv beam-book.pdf site/index.html site/*.png site/*.md5 xml/*.png xml/*.md5 xml/beam-book-from-ab.xml ./images/diag-*.png site/code/*/*.png site/images/*
-	rmdir site/code/* site/images site/code
+	rm -f beam-book.pdf site/index.html site/*.png site/*.md5 xml/*.png xml/*.md5 xml/beam-book-from-ab.xml images/diag-*.png
+	rm -rf site/code site/images .asciidoctor site/.asciidoctor
 
 serve: all
 	cd site && python3 -m http.server

README.md

@@ -136,29 +136,73 @@ an issue declaring what you intend to do.
 
 ## Building the PDF locally from source
 
-The project contains a makefile which
+The project contains a Makefile which
 will let you build your own PDF from the source, provided
-that you have all the needed tools installed.
+that you have all the needed tools installed. Just running
+the command
+```shell
+make
+```
+will build the file `beam-book.pdf` in the top directory
+as well as the HTML version under the `site` directory.
+
+We assume that you already have an Erlang installation of
+your choice for running examples etc. Apart from that, see
+below for what you need in order to build the book.
 
 ### Docker
 
-You can build the project locally using docker by first building the docker image
-```
+You can build the project locally via Docker without having to
+install any addtional software, by first building the docker
+ image. Assuming you have Docker installed, run:
+```shell
 make docker-build
 ```
-And then building the project by
-```
+And then you can build the book by running
+```shell
 make docker
 ```
+(Note: On Linux, the resulting files will be created with
+User ID 1000, regardless of what your current user ID is
+outside Docker. This is due to how Docker integrates with
+the file system.)
+
+#### Devcontainers in the IDE
+
+If you use VSCode or any other editor that has support for
+Devcontainers, this repository contains a configuration that
+can be used out of the box. By opening the project in the dev
+container, you get a shell inside the container with all the
+tools pre-installed and with access to the project files so
+that all you need to do is run `make`.
+
+For a tutorial on devcontainers, see
+[Introduction to Dev Containers](https://happihacking.com/blog/posts/2023/dev-containers/),
+[Decvontainer setup](https://happihacking.com/blog/posts/2023/dev-containers-emacs/),
+and [Devcontainers, UIDs and file permissions](https://happihacking.com/blog/posts/2024/dev-containers-uids/).
+
+If you prefer to build natively rather than use Docker,
+see the following sections depending on your system.
 
 ### Linux
-WIP, to be updated
-```shell
-make
-```
+
+The following should work on a Debian based system, such as Ubuntu:
+1. `apt install git rsync wget curl make`
+1. `apt install ruby ruby-dev default-jre`
+1. `apt install asciidoctor graphviz`
+1. `gem install asciidoctor-pdf asciidoctor-diagram rouge`
+1. `make`
 
 ### Mac OSX
 
+#### Using Homebrew
+
+1. `brew install asciidoctor graphviz wget ditaa`
+1. `gem install asciidoctor-pdf asciidoctor-diagram rouge`
+1. `make`
+
+#### Manual installation
+
 1. Install [asciidoc](https://github.com/asciidoctor/asciidoctor)
 1. Install [asciidoctor-pdf](https://github.com/asciidoctor/asciidoctor-pdf)
 1. Install [asciidoctor-diagram](http://asciidoctor.org/docs/asciidoctor-diagram/)
@@ -168,17 +212,6 @@ make
 1. Install [wget](https://www.gnu.org/software/wget/)
 1. `make`
 
-### Mac OSX (using brew etc)
-
-1. `brew install asciidoctor`
-1. `gem install asciidoctor-pdf`
-1. `gem install asciidoctor-diagram`
-1. `brew install ditaa`
-1. `brew install graphviz`
-1. `gem install rouge`
-1. `brew install wget`
-1. `make`
-
 ## License
 
 _The Erlang Runtime System_ by Erik Stenman is licensed under a

docker/Dockerfile

@@ -1,10 +1,14 @@
 FROM asciidoctor/docker-asciidoctor:latest
 
+# Create a default user instead of root
+RUN adduser --disabled-password --shell /bin/bash builder
+
 RUN apk add --no-cache\
     git\
     rsync\
     erlang
 
+USER builder
 RUN git config --global --add safe.directory /documents
 WORKDIR /documents
 CMD ["make"]