Skip to content

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:

  1. Check if an issue already exists
  2. Open a new issue with a clear description
  3. 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.

Writing a New Guide

Copy the boilerplate and rename it:

cp docs/BOILERPLATE docs/guide_appname.md

Add your application's logo to docs/_static/images/ and update the logo field in your guide's metadata 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
  • New guide: [wordpress] add guide
  • Keep it concise but descriptive

Review Process

  1. 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!

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 spedific 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.

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 image (e.g., _static/images/app.png)
authors List of guide authors (see below)
tags List of categorization tags
website Official project website URL
license The license of the application, e.g. GPLv2
tested Version information (see below)

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.

Tested Versions

Document which version was tested, only keep the tested version:

tested:
  app: "1.0.0"        # Application version
  uberspace: "8.0.0"  # Uberspace version

Guide Structure

Use this structure. Only include applicable sections:

  1. Short description
  2. Prerequisites
  3. Installation
  4. Configuration
  5. Tuning
  6. Updates
  7. Debugging

Guide Header

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

{% include 'guide_header.md' %}

This renders the title, logo, website link, and tested versions automatically.

Code Blocks

Remote Terminal (Uberspace Server)

Use console-remote for commands on the Uberspace server:

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

Always use:

  • Username: isabell
  • Hostname: moondust
  • Prompt: [isabell@moondust ~]$

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/. Assume it's empty.
  • Document database creation when needed.
  • 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 feed for updates and document it.

Link to other guides using relative paths:

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

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/)
    - [MySQL](https://u8manual.uberspace.de/database-mariadb/)

!!! warning

    This will delete all your data!

!!! tip

    You can speed this up by using caching.

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