Contributing to Uberspace 8 Lab¶

Help others run software on Uberspace 8: report a problem, improve a guide, or write a new one. Small fixes are welcome, and you do not need to install anything locally to contribute through Codeberg.

Report a problem¶

Use the issue button on a guide (look for a bug in the upper right corner) or open an issue. Name the Lab Guide or Playbook and explain what's not working as expected. Include relevant commands and errors and any information that might be helpful to resolve the issue.

You can (but don't have to) propose a fix and start a discussion.

Fix a guide¶

Please create an issue before working on your pull request. This way duplicate work is prevented, an issue is the perfect place to discuss and coordinate possible solutions and changes in general.

Lab Guides are in docs/guides. Fork the repository, make your changes and open a pull request. We will review your PR and get in touch.

Add a guide¶

To make adding a new guide as easy as possible we provide a boilerplate with everything you need.

Copy docs/meta/guide_boilerplate to docs/guides/guide_<appname>.md.
Fill in the metadata, add a logo under docs/_static/images/guides/, and replace the example content. Remove optional sections that do not apply.
Test the instructions on a fresh Uberspace 8 Asteroid and record the versions.
Open a pull request describing what you tested (best case you tested every aspect, we know that that's not always possible though) and any remaining questions. We will review your PR and get in touch.

Use a clear title and commit message; we try to use [App] as prefix but don't enforce it. You can add labels or leave that task to us, up to you.

After review, your contribution appears in the Hall of Fame. For every published guide you get a goodie.

What a guide needs¶

The boilerplate supplies the metadata and shared header. Keep these fields: render_macros: true, title, logo, authors, tags, website, license, and tested with quoted app and uberspace versions.

The optional description field supplies the summary for search engines and link previews. Write a short, plain-text sentence describing what readers can expect from the guide.

Every author needs a name and an email address or website/profile URL. These details are public: the Hall of Fame links to the URL when supplied, otherwise to the email address. organization is optional.

Use existing tags from mkdocs.yml → extra.tag_descriptions, if a tag is missing please add it with a short description.

Keep the shared header first, followed by a short introduction, then these sections in order. Omit optional sections when they do not apply.

Section	When needed
Prerequisites	Optional; explain required knowledge in a note before or within this section
Installation	Required; working installation steps
Configuration	Optional
Tuning	Optional
Debugging	Optional
Updates	Required; update steps and a note linking to releases or an update feed
Further Reading	Optional

Write in clear English for readers with basic shell knowledge. Explain unusual steps and flags, use portable paths such as /var/www/virtual/$USER/html/, and show relevant output.

Use console-remote fences for server commands and console for local commands. The usual examples are [isabell@moondust ~]$ and [localuser@localhost ~]$. Use a language fence for configuration files. Link to the Uberspace Manual for shared concepts instead of repeating its instructions. Don't mention additional document roots. Keep it simple. Don't use subfolders. Always use the standard document root /var/www/virtual/$USER/html. Assume the Asteroid is fresh and the document root therefore empty.

Optional local checks¶

Install uv, then run:

uv sync --frozen
uv run -- python hooks/check_guide.py docs/guides/guide_appname.md
uv run -- mkdocs serve --strict

With Task installed, task check runs guide checks, unit tests, and a strict site build. task lint runs the optional local linters. Neither is required to submit a contribution. Automated PR checks report errors, we use the review checklist to assess the instructions themselves.

Code of conduct¶

Be excellent to each other.

Boilerplate¶

---
render_macros: true
title: AppName
description: Install and configure AppName on Uberspace 8.
logo: _static/images/guides/AppName.png
authors:
  - name: Your Name
    # Supply email or url (both are welcome); used publicly in the Hall of Fame.
    url: https://your-website.com
tags:
  - tag1
  - tag2
  - tag3
website: https://example.com/appname
license: AGPLv3
tested:
  app: "1.0.0"
  uberspace: "8.0.0"
---

{% include 'guide_header.md' %}

Short description of the application.

----

!!! note

    For this guide you should be familiar with the basic concepts of:

    * [PHP](https://u8manual.uberspace.de/lang_php/)
    * [MariaDB](https://u8manual.uberspace.de/database_mariadb/)

## Prerequisites

Describe the runtimes and versions this application needs.

You'll need your MariaDB credentials:

```console-remote
[isabell@moondust ~]$ my_print_defaults client
--default-character-set=utf8mb4
--user=isabell
--password=MySuperSecretPassword
```

## Installation

Step-by-step installation instructions...

```console-remote
[isabell@moondust ~]$ cd /var/www/virtual/$USER/html/
[isabell@moondust html]$ wget https://example.com/latest.zip
```

## Configuration

Post-installation configuration steps...

## Tuning

How to make your installation really fly 🚀

## Debugging

Where to look when things are not working as expected.

## Updates

!!! note

    Check the [release page or update feed](https://github.com/example/app/releases.atom) regularly.

Instructions for updating...

## Further Reading

Optional links for debugging, advanced configuration, and deeper documentation:

- [Official documentation](https://example.com/docs): application docs and configuration reference
- [Community support](https://example.com/community): forum or chat for troubleshooting