adoptingerlang / adoptingerlang

Adopting Erlang is an ongoing effort to gather all the resources that will help you use Erlang in a business

Adopting Erlang

Requirements

Two emacs packages are required for converting adoptingerlang.org to pages for the Hugo website or LaTeX for conversion to pdf, mobi, etc. The following can be added to the beginning of your ~/.emacs.d/init.el file if you have one or create that file with this content:

(require 'package)
(add-to-list 'package-archives '("melpa" . "http://melpa.org/packages/"))
(add-to-list 'package-archives '("marmalade" . "http://marmalade-repo.org/packages/"))
(add-to-list 'package-archives '("gnu" . "http://elpa.gnu.org/packages/"))
(package-initialize)

;; Bootstrap `use-package'
(unless (package-installed-p 'use-package)
  (package-refresh-contents)
  (package-install 'use-package))

(eval-when-compile
  (require 'use-package)
  (require 'package))

(dolist (package '(use-package))
   (unless (package-installed-p package)
       (package-install package)))

(use-package org
  :ensure t
  :mode (("\\.org\\'" . org-mode))
  :config
  (progn
    (setq org-startup-indented t)
    (add-hook 'org-mode-hook #'visual-line-mode)
    (setq org-src-fontify-natively t)))

(use-package org-bullets
  :ensure t
  :commands (org-bullets-mode)
  :init (add-hook 'org-mode-hook (lambda () (org-bullets-mode 1))))

(use-package ox-hugo
  :ensure t)

Hugo generated website

See https://ox-hugo.scripter.co/doc/formatting/ for basic Org formatting compared to the Markdown equivalent.

To export a section to its Hugo markdown page move the cursor to the section in adoptingerlang.org and run M-x org-hugo-export-wim-to-md. This will create or update content/docs/<section filename>.md.

The side menu is setup in content/docs/menu/index.md.

LaTeX

Exporting to latex is done with M-x org-latex-export-to-latex.

LaTex to PDF

Easiest way to convert to a pdf is to just use a LaTeX docker image:

$ docker run --rm -it -v .:/source schickling/latex
# pdflatex adoptingerlang.tex

adoptingerlang's Issues

Broken link on OTP Applications page

On the Development/OTP Applications page, the URL for the "Next" link at the bottom of the page appears to be incorrect. When I click on it, I'm sent to a 404 page. Clicking on the link for the following page listed in the Contents at the left-hand side of the page works fine, however.

It looks like the offending hyperlink doesn't point into the Development folder. Compare the broken one: https://adoptingerlang.org/docs/supervision_trees to the working one: https://adoptingerlang.org/docs/development/supervision_trees/ (both taken from https://adoptingerlang.org/docs/development/otp_applications/)

Multi-stage Docker file mount problems for multi-architecture builds

We've found that the suggested multi-stage Dockerfile has problems when it comes to multi-architecture builds. The book suggest to use cache mounts with the attribute sharing=locked (which to my understanding prevents multiple writers to the cache simultaneously, but will always use the cache eventually):

RUN --mount=id=hex-cache,type=cache,sharing=locked,target=/root/.cache/rebar3 \
    rebar3 compile

However, when trying to make multi-architecture builds with Alpine as a base image this problem occurs:

$ docker buildx build --file ./Dockerfile --platform linux/arm64,linux/amd64 --ssh default=$SSH_AUTH_SOCK --tag project .
 => CACHED [linux/amd64 runner 2/4] WORKDIR /opt/project/                  0.0s
 => ERROR [linux/amd64 runner 3/4] RUN --mount=type=cache,id=apk,sharing=  3.6s
 => CACHED [linux/arm64 runner 2/4] WORKDIR /opt/project/                  0.0s
 => [linux/arm64 runner 3/4] RUN --mount=type=cache,id=apk,sharing=locked  3.3s
 => [linux/arm64 builder 4/6] COPY rebar.config rebar.lock ./              0.0s
 => CANCELED [linux/arm64 builder 5/6] RUN apk add --no-cache openssh-cli  0.9s
------
 > [linux/amd64 runner 3/4] RUN --mount=type=cache,id=apk,sharing=locked,target=/var/cache/apk     ln -s /var/cache/apk /etc/apk/cache &&     apk add --update         libstdc++         openssl         ncurses:
#0 3.539 WARNING: Ignoring https://dl-cdn.alpinelinux.org/alpine/v3.16/main: UNTRUSTED signature
#0 3.540 WARNING: Ignoring https://dl-cdn.alpinelinux.org/alpine/v3.16/community: UNTRUSTED signature
#0 3.543 ERROR: unable to select packages:
#0 3.543   libstdc++ (no such package):
#0 3.546     required by: world[libstdc++]
#0 3.546   ncurses (no such package):
#0 3.546     required by: world[ncurses]
#0 3.546   openssl (no such package):
#0 3.546     required by: world[openssl]
------
WARNING: No output specified with docker-container driver. Build result will only remain in the build cache. To push result image into registry use --push or to load image into docker use --load
Dockerfile:79
--------------------
  78 |     # openssl needed by the crypto app
  79 | >>> RUN --mount=type=cache,id=apk,sharing=locked,target=/var/cache/apk \
  80 | >>>     ln -s /var/cache/apk /etc/apk/cache && \
  81 | >>>     apk add --update \
  82 | >>>         libstdc++ \
  83 | >>>         openssl \
  84 | >>>         ncurses
  85 |
--------------------
ERROR: failed to solve: process "/dev/.buildkit_qemu_emulator /bin/sh -c ln -s /var/cache/apk /etc/apk/cache &&     apk add --update         libstdc++         openssl         ncurses" did not complete successfully: exit code: 3

I'm not sure exactly what the problem is, but we suspected some cache contamination between architectures. If we change the flag to sharing=private (which to my understanding will re-use the cache if no-one is using it, but create a new one instead of waiting for a locked one) it works.

See more information here https://docs.docker.com/engine/reference/builder/#run---mounttypecache

Note that we only had to change the sharing flag to private for the lines involving apk.

I'd be happy to do a PR and updating this section with explanations if we agree that this is the proper fix to the problem.

Adopting Erlang – Build Instructions for Linux (OpenSUSE Tumbleweed)

5th of December 2022

If these instructions save anyone else out there from going down the rabbit hole I went down in trying to build the Adopting Erlang eBooks from source, I will gladly provide them!

The first thing you should know is that the instructions for the Emacs build process are correct – see the README.md file here:

[](https://github.com/adoptingerlang/adoptingerlang

I didn’t get as far as generating the Hugo website, such was not my interest or need, but I assume that will work.

For those who are unfamiliar with Emacs, (I myself am more of a Vim guy), you might find these instructions helpful:

[](https://kb.iu.edu/d/acqm

However, on OpenSUSE Tumbleweed, the instructions for the LaTeX build simply do not work at all! I managed to kludge it by fiddling around with the command line arguments, but the resulting PDF was not satisfactory, in that the Table of Contents and internal references were not working properly. Also, I could not create EPUB or MOBI versions of the book at all!

OpenSUSE comes with a barebones installation of LaTeX; however, the texlive dependencies you will need are not installed by default. You will need to install various other dependencies as well.

The first step is to install these:

> sudo zypper in texlive-collection-fontsextra texlive-collection-latexextra texlive-scheme-tetex texlive-cyrillic texlive-pmboxdraw texlive-fncychap texlive-lwa tidy rubber calibre emacs

Expect this step to take several hours, depending on the speed of your network and computer. The texlive dependencies are big!

Then run the Emacs project Tex file build procedure. (First link above.)

Then, to build the PDF:

> pdflatex --shell-escape adoptingerlang.tex

Run this command several times until you stop getting warnings to run it again. (Note that I got warnings about missing includes which I was unable to resolve, however, this does not seem to have materially affected the end result.)

Or, to build the PDF in one step:

> rubber --shell-escape --pdf adoptingerlang

Build the EPUB:

> tex4ebook -s -f epub3 adoptingerlang.tex

Build the MOBI:

> tex4ebook -s -f mobi adoptingerlang.tex

Viola, you’re done! QED!

Adopting.Erlang–Build.Instructions.Linux.pdf

A PDF version of these instructions is attached.

Configuration chapter/url not existant

In https://adoptingerlang.org/docs/development/otp_applications/#what-makes-a-lib-an-app there is a link to a configuration chapter ((see the Configuration chapter)), but gives 404.

Possible typo?

"...which relies on the cache’s ETS table and that table vanishes, then all these processes will may together."

First Release

We might want to aim for a first public release that contains basic content, to gather feedback and build a kind of readership as we then publish more and more stuff over time.

This issue contains tasks we'd have to cover:

• decide which chapters to include (we can pick fewer than currently available)
• write up the intro (even if we rewrite later)
• pick fonts for the web site
• review fonts for the PDF
• choose if we release the PDF along with the website
• fix the text at the top level of a section on the website
• fix up credits for authorship (currently only mentions Tristan) / add bios pages
• add cheat sheets for base Erlang we don't cover
• comment out unwritten chapters for the final deploy stuff
• apply style guide regarding text tone and voice
• make syntax highlighting work
• fix HTML table style
• add Evan's biography
• add twitter / social media links
• mention the release schedule on the main page and where to get updates
• add prev/next links in each chapter
• resize images in the appendix
• fix markdown-style links
• add intro to team-building section

Links with <a href=""> incorrect

It seems like all/many the links with <a href=""> are incorrect. For example the link to systools in: https://adoptingerlang.org/docs/production/docker/#multi-stage-build

I think they should be [[link][target]] or something like that.

Running database migrations?

There's a reference in the Releases chapter to docker-compose up running database migrations, but this is never revisited later in the chapter nor in the next chapter dedicated to Docker.

Is this something that's in the works? It would be really helpful! The topic of database migrations in the context of Docker and "the cloud" in general is not getting enough attention in any of the deployment tutorials I was able to find. I.e. what are some of the "best practices" around this? In the context of a single container deployment? What about multiple containers? Should migrations be run on start-up by the application itself vs delegated to external tools? Etc. etc.

Thanks again for writing this book!

Docker chapter next button bug

If you are in the Docker chapter and you click next, you go straight to Team Building, whereas it should be Kubernetes.

Also thank you for your time, this book is very valuable for experienced newcomers.

Add asdf to installation section