IntenseWebs/distrobox
3
0
Fork 0
mirror of https://github.com/89luca89/distrobox.git synced 2026-08-19 01:14:49 -05:00
Code Issues Packages Projects Releases Wiki Activity

docs(posts): announcing Distrobox v2 (#2032)

Browse Source 
* 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>
This commit is contained in:
Emanuele De Cupis
2026-03-29 18:47:14 +02:00
committed by GitHub
co-authored by 89luca89 Alessio Biancalana Fabrizio Sestito
parent 02da184062
commit 6155b5e33e
3 changed files with 242 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/posts/announcing_distrobox_next.md
+96
View File
@@ -0,0 +1,96 @@
- [Distrobox](README.md)
- [Announcing the next generation of Distrobox](#announcing-the-next-generation-of-distrobox)
- [Try it now](#try-it-now)
- [Why we rewrote Distrobox](#why-we-rewrote-distrobox)
- [Compatibility](#compatibility)
- [During the transition](#during-the-transition)
- [Contributing](#contributing)
- [The many thanks we have to say](#the-many-thanks-we-have-to-say)
---
# Announcing the next generation of Distrobox
We're releasing Distrobox v2 to the public as a release candidate. This is a complete rewrite in Go. Distrobox v1
remains the stable version and we recommend using it in production for now.
The first objective is to reach feature parity between v2 and v1, at which point we can declare v2 stable. The source
code is available now on [the `next` branch](https://github.com/89luca89/distrobox/tree/next).
## Try it now
v2.0.0-rc releases are available on [GitHub](https://github.com/89luca89/distrobox/releases/tag/2.0.0-rc.1).
You can also build from source on the `next` branch:
```sh
git clone https://github.com/89luca89/distrobox.git
cd distrobox
git checkout next
make build
sudo make install
```
Please test it with your usual workflows and report any issues you find. Your feedback is essential to reach stability
quickly.
## Why we rewrote Distrobox
Shell's immediate feedback loop was critical to Distrobox's early success. But as the project matured, we hit its
limits: no proper module system for code reuse, no handy test engine, and patterns that are hard to maintain. We also
want to extend Distrobox to new use cases, which would have required a significant refactor of the existing codebase.
We chose Go because the core team is confident in it. It's popular with a short learning curve, so the community can
jump in and contribute. It has a solid toolchain and standard library that lets us keep external dependencies to a
minimum. And it's straightforward to build for multiple architectures—important for Distrobox's diverse user base.
We didn't start this effort to improve performance. But first benchmarks show a sensible performance increase on common
usage scenarios. More data to come.
## Compatibility
v2 maintains the same interface for CLI command arguments, manifest files, and configuration files. Your scripts and
`.distrobox` folders will work with v2.
Existing v1 containers work with v2, except for exported bins and apps—those containers must be recreated. v2 ships as
a single binary, so command-specific executables like `distrobox-enter` and `distrobox-create` no longer exist. Use
`distrobox enter`, `distrobox create`, etc. instead.
## During the transition
While v2 reaches feature parity and stability, we're making focused choices.
We do not accept new features on v1 nor v2 until v2 reaches feature parity with v1 and is declared stable. New features
would slow down that milestone. Bugfixes must be submitted against the `next` branch. We'll decide on backports to v1
case-by-case.
Before reporting a bug, check whether it's already fixed in v2. For already open PRs on v1, we'll decide case-by-case
with the authors. For open issues on v1, we ask that you verify whether the issue is present on v2 as well. We
prioritize fixing issues on v2 first. We'll consider backporting critical fixes to v1 if the issue makes Distrobox v1
unusable or insecure.
We're releasing v2.0.0-rc versions as we progress. Releases are available on GitHub and are published as needed, with
no fixed cadence. v2 will be declared stable when we can assert it covers all the use cases of v1 without relevant
regressions.
## Contributing
All contributions must be sent against the `next` branch. Please read the
[architecture document](distrobox_next_architecture.md) before contributing.
A working Go installation is required to build and test the project. Refer to the
[official Go documentation](https://go.dev/doc/install) to set up your local environment.
## The many thanks we have to say
A project like Distrobox would have gone nowhere without the support of its community. Over the years, we received
contributions from more than 200 developers; these people are first of all enthusiastic Distrobox users, and we cannot
be more grateful for that.
Some of them are now seeing their code disappear to make room for the rewrite. We want to emphasize that the rewrite
itself wouldn't have been possible without their contributions. Please take a moment to acknowledge the
[Distrobox contributors list](https://github.com/89luca89/distrobox/graphs/contributors) — to them go our warmest
thanks.
We're excited to see where v2 takes Distrobox, and we hope you are excited, too. Try it out, report bugs, and join the
discussion on [Matrix](https://matrix.to/#/%23distrobox:matrix.org) and [Telegram](https://t.me/distrobox_chat_new)
docs/posts/distrobox_next_architecture.md
+144
View File
@@ -0,0 +1,144 @@
- [Distrobox](README.md)
- [Distrobox Go Rewrite: Architecture and Design](#distrobox-go-rewrite-architecture-and-design)
- [Overview](#overview)
- [Directory Structure](#directory-structure)
- [Architecture Layers](#architecture-layers)
- [Dependency Injection Pattern](#dependency-injection-pattern)
- [Configuration System](#configuration-system)
- [Shell Scripts](#shell-scripts)
---
# Distrobox Go Rewrite: Architecture and Design
This document describes the architecture of the Distrobox Go rewrite, explaining how
different layers interact and the design decisions behind the codebase. It's meant to
help contributors understand the system and know where to make changes.
## Overview
The Distrobox Go rewrite is designed with **clear separation of concerns** in mind.
The rewrite followed these principles:
- CLI layer handles command-line parsing and user interaction;
- Container manager implementations are interchangeable;
- UI components can evolve independently;
- The codebase must remains testable and maintainable;
- Dependencies must be kept at minimum.
## Directory Structure
```text
distrobox
├── cmd/distrobox/
│ └── main.go # Entry point
├── internal/
│ ├── cli/ # CLI layer (command definitions)
│ │ ├── root.go # Root command with global flags
│ │ ├── create.go, list.go, etc. # Individual commands
│ │ └── helpers.go
│ ├── config/ # Configuration management
│ ├── inside-distrobox/
│ │ └── assets/ # Embedded shell scripts
├── pkg/
│ ├── commands/ # Business logic layer
│ │ ├── create.go, list.go, etc. # Command implementations
│ ├── containermanager/ # Container abstraction
│ │ ├── containermanager.go # Interface definitions
│ │ └── providers/ # Implementations
│ │ ├── podman.go
│ │ └── docker.go
│ ├── ui/ # UI components
│ │ ├── progress.go
│ │ ├── printer.go
│ │ └── prompt.go
│ └── manifest/ # Manifest parsing
```
## Architecture Layers
### 1. CLI Layer (`internal/cli/`)
The CLI layer handles command-line argument parsing, global flag processing, and
command dispatch. It is also responsible for binding the application to the shell's stdin/stdout,
for loading the configuration, and for instantiating the components.
Among other things, the concerete `ContainerManager` implementation is selected and instantiated in the cli layer.
### 2. Command Layer (`pkg/commands/`)
The command layer contains the business logic for each distrobox operation. Commands
are independent of CLI specifics and can be tested and reused independently.
Commands should be **pure orchestrators**. They coordinate between
the container manager abstraction and UI components, but don't contain low-level
implementation details.
Each command is implemented by a `Execute` method that takes a context and options struct.
### 3. Container Manager Layer (`pkg/containermanager/`)
The container manager is the abstraction over different container runtimes. This design
allows distrobox to work with Docker, Podman, and other container managers without
duplicating logic.
### 4. UI Layer (`pkg/ui/`)
The UI layer provides simple components for user interaction and output formatting.
These are instantiated in the CLI layer and passed to commands.
- **Progress**: Tracks multi-step operations with status indicators
- **Printer**: Formats and displays structured output
- **Prompter**: Gets user confirmation or input
## Dependency Injection Pattern
The architecture uses **context-based dependency injection** to pass the container
manager from the root command to all subcommands.
**Flow:**
```text
main()
↓
LoadConfig()
↓
NewRootCommand().Run()
↓
beforeAction() [global hooks]
↓ Creates container manager
↓ Stores in context
↓
Specific command action (e.g., createAction)
↓ Extracts container manager from context
↓ Creates UI tools
↓ Delegates to command layer
```
This pattern ensures:
- Container manager is available to all commands without global state
- UI tools are created fresh for each invocation
- Testing can substitute different implementations via context
## Configuration System
Configuration is loaded once at startup in `main()`. Configuration sources (in order of precedence):
1. Command-line flags
2. Environment variables (prefixed with `DBX_`)
3. Config file (`~/.config/distrobox/distrobox.conf`)
4. Defaults
This centralized approach makes it easy to understand where values come from and ensures consistency across commands.
## Shell Scripts
When a container is created, part of the `Distrobox` application is loaded in the container
as it is meant to be executed inside it:
- `distrobox-init` serves as the container entrypoint
- `distrobox-export` to expose binaries and applications to the host
- `distrobox-host-exec` to execute host's commands from inside the distrobox
Such commands are POSIX shell scripts that are included as assets in `internal/inside-distrobox/assets`
docs/posts/posts.md
+2
View File
@@ -11,3 +11,5 @@
- [Integrate VSCode and Distrobox](integrate_vscode_distrobox.md)
- [Run Libvirt using distrobox](run_libvirt_in_distrobox.md)
- [Run latest GNOME and KDE Plasma using distrobox](run_latest_gnome_kde_on_distrobox.md)
- [Announcing the next generation of Distrobox](announcing-distrobox-next-gen.md)
- [Distrobox Next architecture](distrobox-next-architecture.md)