[v2] Add minimal devcontainer

From: Mark Jonas <toertel@gmail.com>

The devcontainer can build and run all SWUpdate tests for x86-64
targets. It uses ci/setup.sh to install the required build dependencies.

The devcontainer must be run unpriviledged. Thus, the root user inside
will read and write outside files with the uid and gid of the user who
started the container. This cannot be done using Docker but requires
Podman. Because of this the default container service of VS Code must be
switched from Docker to Podman.

Suggested-by: Ayoub Zaki <ayoub.zaki@embetrix.com>
Suggested-by: Daniel Braunwarth <oss@braunwarth.dev>
Signed-off-by: Mark Jonas <toertel@gmail.com>
---
 .devcontainer/Dockerfile        | 11 +++++++
 .devcontainer/devcontainer.json | 11 +++++++
 .gitignore                      |  3 ++
 DevContainer.md                 | 58 +++++++++++++++++++++++++++++++++
 4 files changed, 83 insertions(+)
 create mode 100644 .devcontainer/Dockerfile
 create mode 100644 .devcontainer/devcontainer.json
 create mode 100644 DevContainer.md

Hi Mark

On 03.01.25 18:16, toertel@gmail.com wrote:
> From: Mark Jonas <toertel@gmail.com>
> 
> The devcontainer can build and run all SWUpdate tests for x86-64
> targets. It uses ci/setup.sh to install the required build dependencies.
> 
> The devcontainer must be run unpriviledged. Thus, the root user inside
> will read and write outside files with the uid and gid of the user who
> started the container. This cannot be done using Docker but requires
> Podman. Because of this the default container service of VS Code must be
> switched from Docker to Podman.
> 
> Suggested-by: Ayoub Zaki <ayoub.zaki@embetrix.com>
> Suggested-by: Daniel Braunwarth <oss@braunwarth.dev>
> Signed-off-by: Mark Jonas <toertel@gmail.com>
> ---
>   .devcontainer/Dockerfile        | 11 +++++++
>   .devcontainer/devcontainer.json | 11 +++++++
>   .gitignore                      |  3 ++
>   DevContainer.md                 | 58 +++++++++++++++++++++++++++++++++
>   4 files changed, 83 insertions(+)
>   create mode 100644 .devcontainer/Dockerfile
>   create mode 100644 .devcontainer/devcontainer.json
>   create mode 100644 DevContainer.md
> 
> diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile
> new file mode 100644
> index 00000000..0347971b
> --- /dev/null
> +++ b/.devcontainer/Dockerfile
> @@ -0,0 +1,11 @@
> +# SPDX-FileCopyrightText: 2024-2025 Mark Jonas <toertel@gmail.com>
> +#
> +# SPDX-License-Identifier: MIT
> +
> +FROM ubuntu:24.04
> +
> +ARG DEBIAN_FRONTEND=noninteractive
> +
> +# Install SWUpdate build dependencies
> +COPY ./ci/setup.sh /tmp
> +RUN chmod +x /tmp/setup.sh && /tmp/setup.sh

Podman is able to build a Dockerfile but the name Containerfile is 
preferred in the podman context.

See 
https://docs.podman.io/en/latest/markdown/podman-build.1.html#description

> diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
> new file mode 100644
> index 00000000..6fd7436a
> --- /dev/null
> +++ b/.devcontainer/devcontainer.json
> @@ -0,0 +1,11 @@
> +// SPDX-FileCopyrightText: 2024-2025 Mark Jonas <toertel@gmail.com>
> +//
> +// SPDX-License-Identifier: MIT
> +
> +{
> +    "name": "SWUpdate Development Container",
> +    "build": {
> +        "dockerfile": "Dockerfile",
> +        "context": ".."
> +    }
> +}

At least "EditorConfig.EditorConfig" as VS Code extensions would be nice 
from my point of view.

Adding port 8080 as forwarded port would probably make sense to be able 
to debug any mongoose problems.

> diff --git a/.gitignore b/.gitignore
> index 4755ff07..24e9a38e 100644
> --- a/.gitignore
> +++ b/.gitignore
> @@ -127,6 +127,9 @@ web-app/swupdate-www.tar.gz
>   !.gitlab-ci.yml
>   !.github
>   
> +# devcontainer
> +!.devcontainer/
> +
>   # swupdateclient
>   Pipfile
>   Pipfile.lock
> diff --git a/DevContainer.md b/DevContainer.md
> new file mode 100644
> index 00000000..56a864e7
> --- /dev/null
> +++ b/DevContainer.md
> @@ -0,0 +1,58 @@
> +<!--
> +SPDX-FileCopyrightText: 2024-2025 Mark Jonas <toertel@gmail.com>
> +
> +SPDX-License-Identifier: MIT
> +-->
> +
> +# Introduction
> +
> +The SWUpdate devcontainer is a Podman-based development environment that
> +ensures consistent tooling and settings across different machines. It uses
> +configuration files to specify the environment setup and automatically builds
> +the required development workspace when opened in compatible IDEs like VS Code.
> +
> +The devcontainer requires Podman because it expects to be run unprivileged.
> +That is, the root user inside the container is expected to read and write
> +files with the uid and gid of the user who started the container.
> +
> +The devcontainer supports compiling and running SWUpdate for x86-64 targets.
> +
> +# Setup
> +
> +## VS Code
> +
> +You have to use *Podman* instead of *Docker* by adding the following to the
> +VS Code user settings. Please note that changing this setting might break other
> +devcontainers you are using which explicitly require Docker. [^1]

What do you want to achieve with this [^1]? At least the VS Code 
Markdown renderer is not able to do anything with this.


> +
> +[^1]: It is an open backlog item of VS Code to change *dev.containers.dockerPath*
> +into a workspace setting. See https://github.com/microsoft/vscode-remote-release/issues/8817

Create a real link:
See <https://github.com/microsoft/vscode-remote-release/issues/8817>.

> +
> +```
> +"dev.containers.dockerPath": "podman"
> +```

Add language to code block:

```json
dev.containers.dockerPath": "podman"
```

> +
> +You can change that setting either in VS Code itself (hotkey *Ctrl-,*) or in
> +the configuration file. VS Code user settings are stored in a *settings.json*
> +file, with different locations depending on your operating system:
> +
> +**Linux**: `$HOME/.config/Code/User/settings.json`
> +
> +**macOS**: `$HOME/Library/Application Support/Code/User/settings.json`
> +
> +**Windows**: `%APPDATA%\Code\User\settings.json`
> +
> +# Usage
> +
> +## Compile and run tests
> +
> +You can compile and run all SWUpdate tests inside the devcontainer. This is very
> +helpful during development and highly recommend before sending a patch to the
> +mailing list.
> +
> +To compile and run all SWUpdate tests, execute the following command using a
> +devcontainer terminal.
> +
> +```
> +ci/test-configs.sh
> +```


Add language to code block:

```sh
ci/test-configs.sh
```


Regards
Daniel

Hi Daniel,

[..]

> > diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile
> > new file mode 100644
> > index 00000000..0347971b
> > --- /dev/null
> > +++ b/.devcontainer/Dockerfile
> > @@ -0,0 +1,11 @@
> > +# SPDX-FileCopyrightText: 2024-2025 Mark Jonas <toertel@gmail.com>
> > +#
> > +# SPDX-License-Identifier: MIT
> > +
> > +FROM ubuntu:24.04
> > +
> > +ARG DEBIAN_FRONTEND=noninteractive
> > +
> > +# Install SWUpdate build dependencies
> > +COPY ./ci/setup.sh /tmp
> > +RUN chmod +x /tmp/setup.sh && /tmp/setup.sh
>
> Podman is able to build a Dockerfile but the name Containerfile is
> preferred in the podman context.
>
> See
> https://docs.podman.io/en/latest/markdown/podman-build.1.html#description

OK. Renamed Dockerfile to Containerfile.

> > diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
> > new file mode 100644
> > index 00000000..6fd7436a
> > --- /dev/null
> > +++ b/.devcontainer/devcontainer.json
> > @@ -0,0 +1,11 @@
> > +// SPDX-FileCopyrightText: 2024-2025 Mark Jonas <toertel@gmail.com>
> > +//
> > +// SPDX-License-Identifier: MIT
> > +
> > +{
> > +    "name": "SWUpdate Development Container",
> > +    "build": {
> > +        "dockerfile": "Dockerfile",
> > +        "context": ".."
> > +    }
> > +}
>
> At least "EditorConfig.EditorConfig" as VS Code extensions would be nice
> from my point of view.

I think that is a good idea for a follow up contribution. I think we
should focus on one feature at a time. That will make it easier for
review and alignment. And we can make sure that the documentation is
still a perfect fit.

> Adding port 8080 as forwarded port would probably make sense to be able
> to debug any mongoose problems.

Same here. IMHO definitely a good idea and can be contributed in a
dedicated followup feature. A paragraph in the documentation
describing the feature similar to the one on how to run the tests
would be great.

[..]

> > +++ b/DevContainer.md
> > @@ -0,0 +1,58 @@
> > +<!--
> > +SPDX-FileCopyrightText: 2024-2025 Mark Jonas <toertel@gmail.com>
> > +
> > +SPDX-License-Identifier: MIT
> > +-->
> > +
> > +# Introduction
> > +
> > +The SWUpdate devcontainer is a Podman-based development environment that
> > +ensures consistent tooling and settings across different machines. It uses
> > +configuration files to specify the environment setup and automatically builds
> > +the required development workspace when opened in compatible IDEs like VS Code.
> > +
> > +The devcontainer requires Podman because it expects to be run unprivileged.
> > +That is, the root user inside the container is expected to read and write
> > +files with the uid and gid of the user who started the container.
> > +
> > +The devcontainer supports compiling and running SWUpdate for x86-64 targets.
> > +
> > +# Setup
> > +
> > +## VS Code
> > +
> > +You have to use *Podman* instead of *Docker* by adding the following to the
> > +VS Code user settings. Please note that changing this setting might break other
> > +devcontainers you are using which explicitly require Docker. [^1]
>
> What do you want to achieve with this [^1]? At least the VS Code
> Markdown renderer is not able to do anything with this.

[^1]: is the notation for a footnote as supported by the markdown
renderers of GitHub and GitLab.

https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#footnotes
https://docs.gitlab.com/ee/user/markdown.html#footnotes

As SWUpdate is hosted on GitHub and its CI/CD it runs on the Denx
GitLab instance, I think it is OK.

What I wanted to achieve is to document that eventually the setting
might become a workspace setting. But that information should not
interrupt the flow of reading.

Do you think it is important that the markdown is perfectly rendered
within VS Code? If yes, how would you substitute the footnote?

> > +
> > +[^1]: It is an open backlog item of VS Code to change *dev.containers.dockerPath*
> > +into a workspace setting. See https://github.com/microsoft/vscode-remote-release/issues/8817
>
> Create a real link:
> See <https://github.com/microsoft/vscode-remote-release/issues/8817>.

I skimmed the MD documentation of GitHub and GitLab and did not find
the <..> notation for links. Both support [..](..) for links with link
text and URL auto-linking for raw links.

In my understanding <..> is reserved for inline HTML tags.

> > +
> > +```
> > +"dev.containers.dockerPath": "podman"
> > +```
>
> Add language to code block:
>
> ```json
> dev.containers.dockerPath": "podman"
> ```

OK. done. Adds a little bit of color.

> > +
> > +You can change that setting either in VS Code itself (hotkey *Ctrl-,*) or in

I changed the formatting of the hotkey to a code block. This looks
similar to how it is done in the official VS Code documentation.

> > +the configuration file. VS Code user settings are stored in a *settings.json*
> > +file, with different locations depending on your operating system:
> > +
> > +**Linux**: `$HOME/.config/Code/User/settings.json`
> > +
> > +**macOS**: `$HOME/Library/Application Support/Code/User/settings.json`
> > +
> > +**Windows**: `%APPDATA%\Code\User\settings.json`
> > +
> > +# Usage
> > +
> > +## Compile and run tests
> > +
> > +You can compile and run all SWUpdate tests inside the devcontainer. This is very
> > +helpful during development and highly recommend before sending a patch to the
> > +mailing list.
> > +
> > +To compile and run all SWUpdate tests, execute the following command using a
> > +devcontainer terminal.
> > +
> > +```
> > +ci/test-configs.sh
> > +```
>
>
> Add language to code block:
>
> ```sh
> ci/test-configs.sh
> ```

OK, done. This did not change anything in the rendered view.

I'll wait a little for further feedback and then send a v3 of the
patch. You can find a preview of the changes I did at
https://gitlab.com/toertel-contribute/swupdate/swupdate/-/tree/feature/devcontainer/
.

Cheers,
Mark