Skip to content
Merged
Changes from all commits
Commits
Show all changes
25 commits
Select commit Hold shift + click to select a range
b66d886
updating introduction
asanvaq Dec 3, 2025
7c5bd63
added how this docs are organized section
asanvaq Dec 3, 2025
89ff344
updated Project and community section
asanvaq Dec 3, 2025
04f60a3
updated in this docs section
asanvaq Dec 3, 2025
6ee95f6
format change
asanvaq Dec 4, 2025
027e306
link update
asanvaq Dec 4, 2025
7321fff
bold section titles
asanvaq Dec 4, 2025
24a7d6b
adding section break lines
asanvaq Dec 4, 2025
9530aec
Merge branch 'main' into updating-homepage
asanvaq Dec 4, 2025
9ebdab7
Removing support link
asanvaq Dec 4, 2025
e8a39f3
Merge branch 'updating-homepage' of github.com:asanvaq/chisel-docs in…
asanvaq Dec 4, 2025
790b834
Removing reference of containers in intro sentence
asanvaq Dec 4, 2025
875d969
Improving security wording
asanvaq Dec 4, 2025
eef8cd0
Adding chisel-releases to proj. and community section
asanvaq Dec 5, 2025
ef20066
Rewording in this documentation section
asanvaq Dec 5, 2025
1120d90
Rewording introductory section
asanvaq Dec 5, 2025
28b0d4f
Spelling correcction and Project and community rewording
asanvaq Dec 5, 2025
ca7db96
Rewording of using chisel
asanvaq Dec 5, 2025
71e0e1f
using relative refs
asanvaq Dec 5, 2025
5c487c1
Update of community statement
asanvaq Dec 10, 2025
bc2134e
Removing security statement
asanvaq Dec 10, 2025
5b994d3
Updating the "in this documentation" section
asanvaq Dec 10, 2025
8cd441a
Moving diataxis statement to the bottom
asanvaq Dec 10, 2025
34d7462
Updated terminology to users
asanvaq Dec 10, 2025
d9555d4
Merge branch 'main' into updating-homepage
asanvaq Dec 10, 2025
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
89 changes: 46 additions & 43 deletions docs/index.md
Original file line number Diff line number Diff line change
@@ -1,68 +1,71 @@
# Chisel

**Chisel** is a tool for carving and cutting Ubuntu packages.
**Chisel** is a developer tool for extracting highly customized and specialized ({{package_slices}}) of Ubuntu packages to create
compact, secure software.

It is built on the idea of {{package_slices}} - minimal, complementary, and
loosely coupled sets of files, based on the package's metadata and content.
Slices are basically logical subsets of the Ubuntu packages, with their own
content and set of dependencies to other internal and external slices.

Chisel is able to extract a highly customised and specialised _Slice_ of the
Ubuntu distribution, which one could see as a block of stone from which we can
carve and extract the small and relevant parts we need to run our applications.

It operates similarly to a package manager, but for package slices, thus being
particularly useful for supporting developers in the creation of smaller but
equally functional container images.
Users need to be able to create software suited to their specific needs with a reduced attack
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I won't block the PR on this, cause it's quite nuanced, but just food for thought: in the line above, Chisel is depicted as a "developer tool". The conotation is different, which doesn't make the use of "Users" wrong here (IMO), but worth noting, just in case you have a different interpretation

surface and a small storage footprint. With Chisel, users build a minimal root filesystem by
selecting and installing only the necessary slices from the full Ubuntu package set.

---------

## In this documentation

````{grid} 1 1 2 2
* **Tutorial**: [Hands-on introduction to Chisel in 15 minutes](tutorial/getting-started)

* **Common patterns**: [Install Chisel](how-to/install-chisel) •
[Slice a package](how-to/slice-a-package/) •
[Use Chisel in a Dockerfile](how-to/use-chisel-in-dockerfile) •
[Explore the Chisel CLI](reference/cmd/index) 

* **Slices**: [Learn more about slices](explanation/slices) •
[Chisel releases](reference/chisel-releases/index) •
[chisel.yaml](reference/chisel-releases/chisel.yaml) •
[Slice definitions](reference/chisel-releases/slice-definitions) •
[Install Ubuntu Pro package slices](how-to/install-pro-package-slices)

```{grid-item-card} [Tutorial](tutorial/getting-started)
---------

**Get started** - become familiar with Chisel by slicing Ubuntu packages to create
a minimal root file system.
```
## How this documentation is organized

```{grid-item-card} [How-to guides](how-to/index)
- The [Tutorial](tutorial/getting-started) takes you step-by-step
through the creation of your first chiseled Ubuntu root file system, from installation to the slicing of Ubuntu
packages.
- [How-to guides](how-to/index) assume you have basic familiarity with
Chisel. They cover tasks such as installation, slicing and usage of Chisel.
- [Reference](reference/index) provides a guide to CLI commands,
chisel-releases and security details.
- [Explanation](explanation/index) includes topic overviews, background
and context and detailed discussion.

**Step-by-step guides** - learn key operations and common tasks.
```
---------

````
## Project and community

````{grid} 1 1 2 2
:reverse:
Chisel is a member of the Ubuntu family. It’s an open source project that warmly welcomes [community contributions](https://documentation.ubuntu.com/project/contributors/).

```{grid-item-card} [Reference](reference/index)
### Get involved

**Technical information** - understand the CLI commands, slice definitions files
and Chisel manifests.
```
* <a href="https://matrix.to/#/#chisel:ubuntu.com">Online chat</a>
* [Contribute](https://github.com/canonical/chisel)

### Releases

```{grid-item-card} [Explanations](explanation/index)
* [Release notes](https://github.com/canonical/chisel/releases)
* [chisel-releases](https://github.com/canonical/chisel-releases)

### Governance and policies

**Discussion and clarification** - explore Chisel's mode of operation and learn
about fundamental topics such as package slices.
```
* [Code of conduct](https://ubuntu.com/community/docs/ethos/code-of-conduct)
* [Security policy](https://github.com/canonical/chisel/blob/main/SECURITY.md)

### Commercial support

````
Thinking about using Chisel for your next project? <a href="https://canonical.com/#get-in-touch#">Get in touch!</a>

---------

## Project and community

Chisel is free software and released under {{AGPL3}}.

The Chisel project is sponsored by {{Canonical}}.

- [Code of conduct](https://ubuntu.com/community/ethos/code-of-conduct)
- [Contribute](https://github.com/canonical/chisel)
- [Security policy](https://github.com/canonical/chisel/blob/main/SECURITY.md)

This documentation uses the [Diátaxis documentation structure](https://diataxis.fr/).
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for being willing to try this out.

This looks good enough for now. But I'd like to find a better place for it still.

Just continue discussing the following on the side:


```{toctree}
:hidden:
Expand Down