Skip to content
Ziwi01Public

Repository files navigation

Proveasio

CI build License Last commit Docs

TL;DR

Set up an Ubuntu terminal environment for development and operations with one Ansible run, and keep it up to date by running it again.

Proveasio installs and configures the tools: zsh, tmux, Neovim, Git helpers, Kubernetes and cloud CLIs, language version managers and AI coding agents. Every tool comes with customizations that make day-to-day terminal work faster.

Supported systems: Ubuntu 24.04 and Ubuntu 26.04, natively or on Windows WSL2. CI tests 26.04. On any other system, use the Docker image.

Quick start

git clone https://github.com/Ziwi01/proveasio.git ~/proveasio
sudo ~/proveasio/prepare-ubuntu.sh
# close and reopen the terminal, then:
cd ~/proveasio/ansible && ansible-playbook -i inventory.yml setup-ubuntu.yml -K

Before the first run, set your git identity in ansible/vars/overrides.yml and read the installation guide.

Or build it as a Docker image:

git clone https://github.com/Ziwi01/proveasio.git ~/proveasio && cd ~/proveasio
USER_UID=$(id -u) USER_GID=$(id -g) docker buildx bake
mkdir -p ~/.local/bin && ln -s ~/proveasio/docker/proveasio ~/.local/bin/proveasio
proveasio init   # then set PROVEASIO_IMAGE=proveasio:local in the file it prints
proveasio        # from any project directory

~/.local/bin must be on your PATH.

See Docker image.

Features

A short summary of the included tools. For details see the documentation; for usage scenarios with examples, see Usage.

Documentation

Contributing

Fork the repository, create a branch from develop, make your changes and open a pull request against develop. See TODO for ideas.

Before you open it, run the checks CI runs:

cd ansible && ansible-lint                                  # must report "Passed: 0 failure(s)"
cd ansible && ansible-playbook -i inventory.yml setup-ubuntu.yml --syntax-check
cd docs-web && npm install && npm run build                 # fails on broken links

Do not run the full playbook on your own machine just to test a change. The Build workflow runs it on a clean Ubuntu runner.

Adding a tool takes five edits: a task file in ansible/roles/software/tasks/ (copy eza.yml or hunk.yml), its include in tasks/main.yml, a github_packages entry in vars/main.yml, a check_software_<tool> in docker/test.sh, and the docs in docs-web/docs/. Commits follow Conventional Commits with a capitalized subject, for example feat(software): Add curlie.

Thanks in advance!

Author

Eryk 'Ziwi' Kozakiewicz

Mentions

Releases

Used by

Contributors

Languages