Contributing to Uberspace 8 Lab¶

We're glad you read this and want to participate in our sweet little laboratory. Our goal is to provide a platform where users can teach and learn from each other and show what's possible with Uberspace.

You're very welcome to add your own guides to this repository. Also whenever you think something is not working as documented or a guide is not self-explaining please let us know.

Reporting Issues¶

If you find a problem with an existing guide or want to make it better:

Check if an issue already exists
Open a new issue with a clear description; title must start with [appname] or [meta] (e.g. [gatus] add guide, [meta] update review checklist)
For bugs, include steps to reproduce

create an issue first

To signify intent and prevent duplicate work, please create an issue before working on your pull request.

Labels¶

Pick one type label when you open an issue or pull request. Maintainers may add triage labels.

Label	When to use
`new guide`	First guide for an application
`guide fix`	Existing guide is wrong, broken, or misleading
`guide update`	Version bump or minor improvements to a published guide
`meta`	Repository tooling: hooks, checklist, contributing, site structure
`ci`	GitLab CI, deploy, or prod pipeline

Label	When to use
`needs review`	Ready for maintainer review (maintainers)
`wip`	Work in progress — not ready for review
`blocked`	Waiting on upstream, manual, or a maintainer decision

The [appname] or [meta] prefix in the title names the scope; labels describe the kind of work. Do not use per-app labels — the title already carries the app name.

Enforcement: Blank issues are disabled (.gitea/ISSUE_TEMPLATE/). The validate-issue-title Forgejo Action closes issues whose titles do not match [tag] description (e.g. test is rejected). Actions must be enabled in the repository settings (Units → Overview) for this to run.

Writing a New Guide¶

Copy the boilerplate and rename it:

cp docs/meta/guide_boilerplate docs/guide_appname.md

Add your application's logo to docs/_static/images/guides/ and update the logo field in your guide's front matter to match the path. Use SVG (preferred) or PNG with transparent background.

Test all instructions on a fresh Uberspace 8 Asteroid.

Commit Messages¶

Start with [appname] prefix: [wordpress] add update info
Repo/meta/tooling changes: [meta] … (e.g. [meta] add check_guide hook)
New guide: [wordpress] add guide
Keep it concise but descriptive

Do not use Conventional Commits (feat:, doc:, chore:) in this repo. Merge and revert commits are exempt. Enforced by hooks/check_commit_message.py at the commit-msg stage.

Review Process¶

Submit your pull request. We will review your guide and give you feedback. Once approved, your guide gets merged and you join the Hall of Fame and get a goodie of your choice!

Maintainers use the Guide Review Checklist when reviewing pull requests.

Maintaining Your Guide

If possible, please stay available for questions and issues after publishing, and help keep the guide up to date when new versions are released.

Code of Conduct¶

Be excellent to each other.

Style Guide¶

Guides have specific style and formatting conventions. Following these guidelines ensures consistency and readability.

General Writing Guidelines¶

Language: English (en_US). You don't have to be a native speaker or a poet.
Clarity: Write clearly and directly.
Audience: Assume basic Linux and shell knowledge, but explain complex concepts.

File Naming¶

Use guide_<appname>.md for guide filenames (e.g. guide_wordpress.md). Use <appname>.(png|svg) for the logo under docs/_static/images/guides/.

Guide Metadata¶

Every guide must start with YAML front matter. See the boilerplate for a complete example.

Required Fields¶

Field	Description
`render_macros`	Must be `true` to enable template rendering
`title`	The application name (used in header and title)
`logo`	Path to logo under `docs/_static/images/guides/` (e.g. `guides/app.png`)
`authors`	List of guide authors (see below)
`tags`	List of categorization tags (see Tags)
`website`	Official project website URL (`http(s)://`)
`license`	The license of the application, e.g. `GPLv2`
`tested`	Version information (see Tested Versions)

Authors¶

Authors appear in the Hall of Fame.

Field	Required	Description
`name`	Yes	Your display name
`email`	No	Contact email (used for Hall of Fame link if no URL)
`url`	No	Personal website (preferred link in Hall of Fame)
`organization`	No	Company or organization name

Example:

authors:
- name: Jane Doe
  email: jane@example.com
  url: https://janedoe.dev
- name: John Smith
  organization: ACME Corp

Tags¶

Tags categorize guides. Available tags are defined in mkdocs.yml under extra.tag_descriptions. Use existing tags when possible; add new ones there when needed. hooks/check_tags.py enforces that every guide tag has a matching entry.

Tested Versions¶

Document which version was tested. Keep only the version you actually tested:

tested:
  app: "1.0.0"        # Application version
  uberspace: "8.0.0"  # Uberspace version — no "v" prefix

Guide Structure¶

Use this structure in order. Mandatory sections must be present; omit optional sections when they do not apply.

Section	Required
Short description	mandatory
Prerequisites	optional
Installation	mandatory
Configuration	optional
Tuning	optional
Updates	mandatory
Debugging	optional
Further Reading	optional

Sections are separated by a ---- (four dashes) line. The first ---- goes between the short description and the prerequisites note.

Guide Header¶

Every guide must start with the shared header template on the first line after the front matter:

{% include 'guide_header.md' %}

This renders the title, logo, website link, license, and tested versions automatically (see templates/guide_header.md).

Code Blocks¶

Remote Terminal (Uberspace Server)¶

Use console-remote for commands run on the Uberspace server:

```console-remote
[isabell@moondust ~]$ uberspace web domain list
isabell.uber.space
```

Always use:

Username: isabell
Hostname: moondust (never stardust)
Prompt: [isabell@moondust ~]$ with a trailing $
Working directory reflected in subsequent prompts (e.g. [isabell@moondust html]$)

Never put an [isabell@moondust prompt inside a console block — use console-remote.

Local Terminal¶

Use console for commands on the user's local machine:

```console
[localuser@localhost ~]$ ssh isabell@moondust.uberspace.de
```

Configuration Files¶

Use appropriate language identifiers, e.g.:

```ini
[program:myapp]
directory=%(ENV_HOME)s/myapp
command=/usr/bin/python app.py
```

```yaml
database:
  host: localhost
  name: isabell_myapp
```

Content Guidelines¶

Don't mention additional document roots. Keep it simple. Don't use subfolders.
Always use full paths. Don't assume the home directory.
Use the standard document root /var/www/virtual/$USER/html/. Assume it's empty.
Document database creation when needed. Use mariadb / mariadb-dump (not mysql / mysqldump) and say "MariaDB" in prose. Database names follow ${USER}_appname. Fetch credentials with my_print_defaults client.
Document directory creation when needed.
Include output of shell commands when relevant.
Explain non-obvious flags. Prefer long versions (--verbose).
If there are default passwords, tell users to change them.
Don't use cat > file <<EOF. Tell users to edit the file.
If the app writes logs, add a symlink to ~/logs.
Try to find an RSS or Atom feed for updates and document it in the ## Updates section.

Internal Links¶

Link to other guides using relative paths:

Check out the [WordPress guide](../guide_wordpress.md) for more info.

Manual Links¶

Link to Manual pages using absolute URLs:

See the [PHP documentation](https://u8manual.uberspace.de/lang_php/) for details.

Admonitions¶

Use admonitions for important information:

!!! 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/)

!!! warning

    This will delete all your data!

!!! tip

    You can speed this up by using caching.

The ## Prerequisites and ## Updates sections each start with a !!! note admonition (see the boilerplate).

Linting Your Guide¶

Run the guide linter before opening a pull request:

# Changed guides vs main
./hooks/check_guide.sh --changed

# Explicit file(s)
./hooks/check_guide.sh docs/guide_appname.md

# All guides
./hooks/check_guide.sh --all

# Treat consistency warnings as errors
./hooks/check_guide.sh --changed --strict

Issues are reported as MUST (blocking) or SHOULD (consistency; only blocks with --strict). The script runs hooks/check_tags.py, ripgrep pattern checks, and hooks/check_guide.py (structure, front matter, prompts, MariaDB wording). See the review checklist for what each layer flags.

The full pre-commit suite (ruff, pymarkdown, shellcheck, uv-lock, …) runs over all files via task lint. Pre-commit is not enforced in CI — it runs locally only.

Boilerplate¶

---
render_macros: true
title: AppName
logo: _static/images/guides/AppName.png
authors:
  - name: Your Name
    email: your.email@example.com
    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/)
    * [AnotherFancyLanguage](https://u8manual.uberspace.de/lang_fancy/)
    * ...

## Prerequisites

We're using [PHP](https://u8manual.uberspace.de/lang_php/) in the stable version 8.3 and [AnotherFancyLanguage](https://u8manual.uberspace.de/lang_fancy/) in Version 42.

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 [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