uberspace/lab

The Uberlab provides various tutorials - written by you! - on how to run software and tools on Uberspace 7.

Uberspace 7 Lab

Welcome to our laboratory! 🎉

This is where we host the source code of the official version over at https://lab.uberspace.de. The lab contains a collection of guides and tips on how to run specific software on Uberspace 7. Most of the guides are contributed by users like you! So, if you'd like to change or add something here, you're more than welcome to do so. Have a look at our contributing guidelines to learn how. Also, have a look at the list of guides people are looking for!

Prerequisites

You need to have installed:

• Python (<= 3.11)
• Enchant library

Development

Pushing for each and every change is fun, but can take some time. To speed up your development process, the lab can be built locally.

Initial Setup

make setup

Building

source .venv/bin/activate
make clean html

The HTML views are now present in build/html.

Development Server

To build automatically on each change use sphinx-autobuild:

make clean serve

This will start a local webserver on http://127.0.0.1:8000, which always serves the most recent version.

Linting

To lint all files, you can use pre-commit:

make lint

Or just to check the guides for consistency:

make check-guides

Spellcheck

To check the spelling you can use the spell check function of Sphinx:

make spelling

Add Words to Guide

If your guide needs to use words, that should not go into the global dictionary (see below), you can flag them with the spelling directive like this (usually near the top of your guide):

.. spelling::
    passwörd
    anotherword

Add Words to Global Dictionary

1. run make get-new-words to write a list of all spelling errors found to new_words.txt
2. edit the resulting new_words.txt
   1. decide wich words to keep for the global dict,
   2. and wich might be better put into a guide local list (see the spelling directive above for that)
3. if satisfied, run make add-new-words to merge them to the global dictionary
4. commit your changes ✏️

License

All text and code in this repository is licensed under CC-BY-NC-SA 4.0. All project logos are property of the respective project.

lab's Issues

Wallabag Guide

I am working on writing a wallabag guide

update style guide with FAQs

Add the following questions to our style guide:

• #43
• #42
• #39
• #36

add a guide for pretalx

Pretalx is a popular opensource event planning solution. It can be used to collect talks and workshops for small to medium sized events. Being a django application it is fairly easy to deploy. Follow the official guide and credit it.

Standardpaths

Are there standard paths we can assume for the letsencrypt certs and similiar things?
If so they should probably be mentioned in sources/README.md

logo overlaps content, if first paragraph is too short

See #86, cb4a880

add a guide for podlove

Add a guide to install podlove on top of an existing wordpress installation. Mention podseed for the actual audio files, so users do not overwhelm the traffic and storage of their spaces.

Improve Ghost logo

The logo used in the Ghost guide ia a PNG with white-background which doesn't look in the logo area. Replace it with a transparent version instead.

WordPress: install and manage/update with wp-cli

What do you think about a more modern approach to managing WordPress with the official WordPress command line interface wp-cli? It offers commands to not only install and update the WordPress core but also plugins and themes.

Here's a simple example from the wp-cli docs to download and install WordPress:

# Download WordPress core
$ wp core download --locale=nl_NL
Downloading WordPress 4.5.2 (nl_NL)...
md5 hash verified: c5366d05b521831dd0b29dfc386e56a5
Success: WordPress downloaded.

# Install WordPress
$ wp core install --url=example.com --title=Example --admin_user=supervisor --admin_password=strongpassword [email protected]
Success: WordPress installed successfully.

Multiple Ports in one Guide

If I need to use multiple ports in one guide,
should I just use 9000,9001,9002, are they surely blocked?

Change project name to lab in config

add tags

Some tags like PHP, Node.js, Blog, Calendar, Contacts, etc. would be nice.

add a guide for pretix

Pretix is a popular opensource ticketing solution. It can be used to sell tickets for workshops, events or even just limit the number of people for a free event. Being a django application it is fairly easy to deploy. There is an existing, recent guide for U6. Kindly ask the author for permission, credit them in the guide, port it to U7 and replace sqlite with mysql.

create landing page

Explicit Folders

Should guides create directories for files explicitly to make the easier to use for beginners?

center logo

due to the rocket the logo on the left is is not centered anymore. Fix with CSS:

.wy-side-nav-search { background-position-x: 1.8em; }

Guide synapse matrix server

Currently working on a guide for the synapse matrix server

git clone without history?

Should git clone commands be used wit --depth 1 to omit history data? Most of the users wont need them, and if so they would know how to get them.
Sometimes commit histories are quite large and downloading them again and again just creates traffic and harms the environment ;)

Wordpress

add authors to lychee

The lychee guide is missing the authors. Add them.

add tested versions to gitea

The gittea guide does not specify the tested gitea and uberspace versions. Add them.

provide skeleton for articles in README

• Prerequisites
• Installation
• Configuration
• Finishing installation
• Updates

Opening Ports

What should be done if open ports are needed

Change "view page source" to "edit on Github"

See https://sphinx-rtd-theme.readthedocs.io/en/latest/configuring.html#page-level-configuration

add sidebar to Wordpress

Should contain the following information:

Tested Wordpress version
Tested Uberspace 7 version

add logo to wallabag

The wallabag guide is missing a logo. Add them.

Linuxbrew

How about software that requires a licence?

The old cool stuff and the guides written were primarely focused on free and open source software. But there are e.g. CMS like Kirby that require a licence to be used in production. Before I start working on a guide I would like to ask if this is ok for the Uberspace staff or if it's undesired.

update via git requires configuration

Some guides advise to update via git pull ... but that fails when there is no name/email configured for git. Should this problem be explained somehow or can we trust in the users that they understand the elaborate error message ?

From https://github.com/user/software
 * branch              master     -> FETCH_HEAD

*** Please tell me who you are.

Run

  git config --global user.email "[email protected]"
  git config --global user.name "Your Name"

to set your account's default identity.
Omit --global to set the identity only in this repository.

fatal: empty ident name (for <[email protected]>) not allowed

make master the production branch

We currently use stable as our production branch on lab.uberspace.de. Since we do not need release management and two stages of review in this case, just use master.

Choose license

CC-BY-NC-SA? CC-BY? MIT/BSD?

add contributing guidelines

https://help.github.com/articles/setting-guidelines-for-repository-contributors/

A contribution guideline should outline ...

• which kinds of issues and pull requests we'd like to see
• which format those issues should have
• which format, language and style new guides should have
• formalities (e.g. licensing)
• a (short) CoC
• tell people to use feature branches, how to do it and how to fix a butchered master
• ask them to leave a name and optionally a link to their homepage/blog for hall of fame
• probably more 📦

Add changelog feed

Github provides a feed for commits to the master branch.

use the same username in all guides

We currently use a different username for each guide (e.g. wordpress for wordpress, ghost for ghost). This increases the work we have with maintaining guides, makes it hard to copy code around and makes it impossible to reuse snippets without causing confusion. Additionally, we used female-sounding names in the past to make a statement, which we can't do with project-names as usernames.

• make up a single username to use in all guides
• change all existing guides to match
• document this in our style guide

NextCloud

add author to each guide and generate hall of fame

Since we have sectionauthorin every guide now, it would be nice to display that information in the footer.
Some kind of "Hall of fame" would be nice, maybe a link to the contributors is fine too.

Question "Lockfile"

Are any measures planned to prevent double work, eg two users writing the same manual?

composer guide

wallabag needs composer, so writing a small composer install guide, too :)

think about incentives

Our awesome users should get rewarded for participation. Think about incentives for:

• New guides
• Fixing bugs in guides

use globbing in toctree

rename all guides to guide_* and use globbing

.. toctree::
   :glob:

   guide_*

in index.rst. This way our toc is always up to date and we don't have to sort the entries.

Use the same username throughout Ghost article

Currently it's a mix of ghost and isabell

add sidebar to Ghost

Should contain the following information:

• Tested Ghost version
• Tested Uberspace 7 version

add note about logo licenses to footer

We currently have a note in our readme stating that all logs are of course not CC-licensed by us, but are property of the respective projects. Add a similar note to the footer.

add contributors to each guide

We should credit all the nice people who have written guides for our lab. Maybe a nice box listing their names at the top or bottom of each guide will do?

polish allauthors

• Sort the output of .. allauthors:: by contrubutions
• When there is no author set the author to Uberspace
• When there is a URL for the author instead of a email address (Uberspace <uberspace.de>), link to that URL (Uberspace).

add authors to wallabag

The wallabag guide is missing the authors. Add them.

Ease of Use: Databases

Should the generation of needed databases be included ?

fix `domains` link in gitea

Footer layout

On certain devices the footer version date overlaps with the asteroid, because the sphind line has no line break

Etherpad: Switch to NODE_ENV=production

WIP: Ghost