Skip to content

Commit 6155b5e

Browse files
balanza89luca89dottorblasterfabriziosestito
authored
docs(posts): announcing Distrobox v2 (#2032)
* docs(posts): announcing v2 post Co-authored-by: 89luca89 <luca.dimaio1@gmail.com> Co-authored-by: Alessio Biancalana <alessio@dottorblaster.it> Co-authored-by: Fabrizio Sestito <fabrizio.sestito@suse.com> * docs(posts): distrobox next architecture Co-authored-by: 89luca89 <luca.dimaio1@gmail.com> Co-authored-by: Alessio Biancalana <alessio@dottorblaster.it> Co-authored-by: Fabrizio Sestito <fabrizio.sestito@suse.com> * docs: fix link to distrobox next architecture --------- Co-authored-by: 89luca89 <luca.dimaio1@gmail.com> Co-authored-by: Alessio Biancalana <alessio@dottorblaster.it> Co-authored-by: Fabrizio Sestito <fabrizio.sestito@suse.com>
1 parent 02da184 commit 6155b5e

3 files changed

Lines changed: 242 additions & 0 deletions

File tree

‎docs/posts/announcing_distrobox_next.md‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
- [Distrobox](README.md)
2+
- [Announcing the next generation of Distrobox](#announcing-the-next-generation-of-distrobox)
3+
- [Try it now](#try-it-now)
4+
- [Why we rewrote Distrobox](#why-we-rewrote-distrobox)
5+
- [Compatibility](#compatibility)
6+
- [During the transition](#during-the-transition)
7+
- [Contributing](#contributing)
8+
- [The many thanks we have to say](#the-many-thanks-we-have-to-say)
9+
10+
---
11+
12+
# Announcing the next generation of Distrobox
13+
14+
We're releasing Distrobox v2 to the public as a release candidate. This is a complete rewrite in Go. Distrobox v1
15+
remains the stable version and we recommend using it in production for now.
16+
17+
The first objective is to reach feature parity between v2 and v1, at which point we can declare v2 stable. The source
18+
code is available now on [the `next` branch](https://github.com/89luca89/distrobox/tree/next).
19+
20+
## Try it now
21+
22+
v2.0.0-rc releases are available on [GitHub](https://github.com/89luca89/distrobox/releases/tag/2.0.0-rc.1).
23+
24+
You can also build from source on the `next` branch:
25+
26+
```sh
27+
git clone https://github.com/89luca89/distrobox.git
28+
cd distrobox
29+
git checkout next
30+
make build
31+
sudo make install
32+
```
33+
34+
Please test it with your usual workflows and report any issues you find. Your feedback is essential to reach stability
35+
quickly.
36+
37+
## Why we rewrote Distrobox
38+
39+
Shell's immediate feedback loop was critical to Distrobox's early success. But as the project matured, we hit its
40+
limits: no proper module system for code reuse, no handy test engine, and patterns that are hard to maintain. We also
41+
want to extend Distrobox to new use cases, which would have required a significant refactor of the existing codebase.
42+
43+
We chose Go because the core team is confident in it. It's popular with a short learning curve, so the community can
44+
jump in and contribute. It has a solid toolchain and standard library that lets us keep external dependencies to a
45+
minimum. And it's straightforward to build for multiple architectures—important for Distrobox's diverse user base.
46+
47+
We didn't start this effort to improve performance. But first benchmarks show a sensible performance increase on common
48+
usage scenarios. More data to come.
49+
50+
## Compatibility
51+
52+
v2 maintains the same interface for CLI command arguments, manifest files, and configuration files. Your scripts and
53+
`.distrobox` folders will work with v2.
54+
55+
Existing v1 containers work with v2, except for exported bins and apps—those containers must be recreated. v2 ships as
56+
a single binary, so command-specific executables like `distrobox-enter` and `distrobox-create` no longer exist. Use
57+
`distrobox enter`, `distrobox create`, etc. instead.
58+
59+
## During the transition
60+
61+
While v2 reaches feature parity and stability, we're making focused choices.
62+
63+
We do not accept new features on v1 nor v2 until v2 reaches feature parity with v1 and is declared stable. New features
64+
would slow down that milestone. Bugfixes must be submitted against the `next` branch. We'll decide on backports to v1
65+
case-by-case.
66+
67+
Before reporting a bug, check whether it's already fixed in v2. For already open PRs on v1, we'll decide case-by-case
68+
with the authors. For open issues on v1, we ask that you verify whether the issue is present on v2 as well. We
69+
prioritize fixing issues on v2 first. We'll consider backporting critical fixes to v1 if the issue makes Distrobox v1
70+
unusable or insecure.
71+
72+
We're releasing v2.0.0-rc versions as we progress. Releases are available on GitHub and are published as needed, with
73+
no fixed cadence. v2 will be declared stable when we can assert it covers all the use cases of v1 without relevant
74+
regressions.
75+
76+
## Contributing
77+
78+
All contributions must be sent against the `next` branch. Please read the
79+
[architecture document](distrobox_next_architecture.md) before contributing.
80+
81+
A working Go installation is required to build and test the project. Refer to the
82+
[official Go documentation](https://go.dev/doc/install) to set up your local environment.
83+
84+
## The many thanks we have to say
85+
86+
A project like Distrobox would have gone nowhere without the support of its community. Over the years, we received
87+
contributions from more than 200 developers; these people are first of all enthusiastic Distrobox users, and we cannot
88+
be more grateful for that.
89+
90+
Some of them are now seeing their code disappear to make room for the rewrite. We want to emphasize that the rewrite
91+
itself wouldn't have been possible without their contributions. Please take a moment to acknowledge the
92+
[Distrobox contributors list](https://github.com/89luca89/distrobox/graphs/contributors) — to them go our warmest
93+
thanks.
94+
95+
We're excited to see where v2 takes Distrobox, and we hope you are excited, too. Try it out, report bugs, and join the
96+
discussion on [Matrix](https://matrix.to/#/%23distrobox:matrix.org) and [Telegram](https://t.me/distrobox_chat_new)

‎docs/posts/distrobox_next_architecture.md‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
- [Distrobox](README.md)
2+
- [Distrobox Go Rewrite: Architecture and Design](#distrobox-go-rewrite-architecture-and-design)
3+
- [Overview](#overview)
4+
- [Directory Structure](#directory-structure)
5+
- [Architecture Layers](#architecture-layers)
6+
- [Dependency Injection Pattern](#dependency-injection-pattern)
7+
- [Configuration System](#configuration-system)
8+
- [Shell Scripts](#shell-scripts)
9+
10+
---
11+
12+
# Distrobox Go Rewrite: Architecture and Design
13+
14+
This document describes the architecture of the Distrobox Go rewrite, explaining how
15+
different layers interact and the design decisions behind the codebase. It's meant to
16+
help contributors understand the system and know where to make changes.
17+
18+
## Overview
19+
20+
The Distrobox Go rewrite is designed with **clear separation of concerns** in mind.
21+
The rewrite followed these principles:
22+
23+
- CLI layer handles command-line parsing and user interaction;
24+
- Container manager implementations are interchangeable;
25+
- UI components can evolve independently;
26+
- The codebase must remains testable and maintainable;
27+
- Dependencies must be kept at minimum.
28+
29+
## Directory Structure
30+
31+
```text
32+
distrobox
33+
├── cmd/distrobox/
34+
│ └── main.go # Entry point
35+
├── internal/
36+
│ ├── cli/ # CLI layer (command definitions)
37+
│ │ ├── root.go # Root command with global flags
38+
│ │ ├── create.go, list.go, etc. # Individual commands
39+
│ │ └── helpers.go
40+
│ ├── config/ # Configuration management
41+
│ ├── inside-distrobox/
42+
│ │ └── assets/ # Embedded shell scripts
43+
├── pkg/
44+
│ ├── commands/ # Business logic layer
45+
│ │ ├── create.go, list.go, etc. # Command implementations
46+
│ ├── containermanager/ # Container abstraction
47+
│ │ ├── containermanager.go # Interface definitions
48+
│ │ └── providers/ # Implementations
49+
│ │ ├── podman.go
50+
│ │ └── docker.go
51+
│ ├── ui/ # UI components
52+
│ │ ├── progress.go
53+
│ │ ├── printer.go
54+
│ │ └── prompt.go
55+
│ └── manifest/ # Manifest parsing
56+
```
57+
58+
## Architecture Layers
59+
60+
### 1. CLI Layer (`internal/cli/`)
61+
62+
The CLI layer handles command-line argument parsing, global flag processing, and
63+
command dispatch. It is also responsible for binding the application to the shell's stdin/stdout,
64+
for loading the configuration, and for instantiating the components.
65+
66+
Among other things, the concerete `ContainerManager` implementation is selected and instantiated in the cli layer.
67+
68+
### 2. Command Layer (`pkg/commands/`)
69+
70+
The command layer contains the business logic for each distrobox operation. Commands
71+
are independent of CLI specifics and can be tested and reused independently.
72+
73+
Commands should be **pure orchestrators**. They coordinate between
74+
the container manager abstraction and UI components, but don't contain low-level
75+
implementation details.
76+
77+
Each command is implemented by a `Execute` method that takes a context and options struct.
78+
79+
### 3. Container Manager Layer (`pkg/containermanager/`)
80+
81+
The container manager is the abstraction over different container runtimes. This design
82+
allows distrobox to work with Docker, Podman, and other container managers without
83+
duplicating logic.
84+
85+
### 4. UI Layer (`pkg/ui/`)
86+
87+
The UI layer provides simple components for user interaction and output formatting.
88+
These are instantiated in the CLI layer and passed to commands.
89+
90+
- **Progress**: Tracks multi-step operations with status indicators
91+
- **Printer**: Formats and displays structured output
92+
- **Prompter**: Gets user confirmation or input
93+
94+
## Dependency Injection Pattern
95+
96+
The architecture uses **context-based dependency injection** to pass the container
97+
manager from the root command to all subcommands.
98+
99+
**Flow:**
100+
101+
```text
102+
main()
103+
↓
104+
LoadConfig()
105+
↓
106+
NewRootCommand().Run()
107+
↓
108+
beforeAction() [global hooks]
109+
↓ Creates container manager
110+
↓ Stores in context
111+
↓
112+
Specific command action (e.g., createAction)
113+
↓ Extracts container manager from context
114+
↓ Creates UI tools
115+
↓ Delegates to command layer
116+
```
117+
118+
This pattern ensures:
119+
120+
- Container manager is available to all commands without global state
121+
- UI tools are created fresh for each invocation
122+
- Testing can substitute different implementations via context
123+
124+
## Configuration System
125+
126+
Configuration is loaded once at startup in `main()`. Configuration sources (in order of precedence):
127+
128+
1. Command-line flags
129+
2. Environment variables (prefixed with `DBX_`)
130+
3. Config file (`~/.config/distrobox/distrobox.conf`)
131+
4. Defaults
132+
133+
This centralized approach makes it easy to understand where values come from and ensures consistency across commands.
134+
135+
## Shell Scripts
136+
137+
When a container is created, part of the `Distrobox` application is loaded in the container
138+
as it is meant to be executed inside it:
139+
140+
- `distrobox-init` serves as the container entrypoint
141+
- `distrobox-export` to expose binaries and applications to the host
142+
- `distrobox-host-exec` to execute host's commands from inside the distrobox
143+
144+
Such commands are POSIX shell scripts that are included as assets in `internal/inside-distrobox/assets`

‎docs/posts/posts.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,3 +11,5 @@
1111
- [Integrate VSCode and Distrobox](integrate_vscode_distrobox.md)
1212
- [Run Libvirt using distrobox](run_libvirt_in_distrobox.md)
1313
- [Run latest GNOME and KDE Plasma using distrobox](run_latest_gnome_kde_on_distrobox.md)
14+
- [Announcing the next generation of Distrobox](announcing-distrobox-next-gen.md)
15+
- [Distrobox Next architecture](distrobox-next-architecture.md)

0 commit comments

Comments
 (0)