mcpringle/apus repository overview

⁠Apus

⁠About

Apus is a social media wall for conferences.

The name Apus is based on Apus Apus, Latin for common swift. This is a bird species that is extremely adapted to a life in the air and can stay in the air for around ten months almost without interruption and can reach speeds of more than 200 km/h during flight maneuvers. This bird breeds in a wall, flies reliably for extremely long periods without crashing and is also extremely fast. Hopefully all of this also applies to Apus: fast execution, uninterrupted and reliable operation!

See:

• https://en.wikipedia.org/wiki/Common_swift⁠
• https://en.wikipedia.org/wiki/Apus_(bird)⁠

⁠Mission Statement

🇬🇧
Apus connects conference attendees in real time: Our application displays the up-to-date program with current and upcoming presentations as well as live-shared impressions from social networks. We provide orientation, foster interaction, and turn every event into a connected experience.

🇩🇪
Apus bringt Konferenzteilnehmer in Echtzeit zusammen: Unsere Anwendung zeigt das aktuelle Programm mit laufenden und bevorstehenden Vorträge sowie live geteilte Eindrücke aus sozialen Netzwerken. So schaffen wir Orientierung, fördern Interaktion und machen jede Veranstaltung zu einem vernetzten Erlebnis.

⁠Features

⁠Show posts from Social Media

⁠Show event agenda

⁠And more

⁠Running in Production

It is highly recommended to use Docker⁠ or Podman⁠ to run Apus in production. Here follows a very short explanation of the example commands below. Consult the Docker or Podman documentation for more information about all available options for running an image.

Modify the following commands according to your needs and consult the configuration section⁠ below for more information about how to configure Apus. The Docker image of Apus will be pulled from Docker Hub⁠ automatically when not available locally.

⁠Using Docker

docker run \
    --name apus \
    -p 80:8080 \
    -e APUS_SOCIAL_HASHTAGS=java \
    -e APUS_TIMEZONE=Europe/Zurich \
    -d \
    --rm \
    mcpringle/apus

⁠Using Podman

The parameters are the same like in in the Docker example, but the image must be prefixed with docker.io/:

podman run \
    --name apus \
    -p 80:8080 \
    -e APUS_SOCIAL_HASHTAGS=java \
    -e APUS_TIMEZONE=Europe/Zurich \
    -d \
    --rm \
    docker.io/mcpringle/apus

⁠Configuration

Apus can be started without any specific configuration. All configuration options have working default values.

⁠Configuration Options

To modify the default configuration values, just specify environment variables with the following names:

The environment variables will override the default values. Some default values might be too long to be displayed in this table. They are marked with a number in square brackets and can be looked up in the following list:

1. https://${instance}/xrpc/app.bsky.feed.searchPosts?q=%23${hashtag}&tag=${hashtag}&limit=${limit}
2. https://${instance}/xrpc/app.bsky.feed.searchPosts?q=%40${profile}&mentions=${profile}&limit=${limit}
3. https://${event}.cfp.dev/api/public/schedules/${weekday}
4. https://meine.doag.org/api/event/action.getCPEventAgenda/eventId.${event}
5. https://${instance\/api/v1/notifications?types[]=mention&limit=${limit}
6. https://${instance}/api/v1/timelines/tag/${hashtag}?limit=${limit}
7. https://sessionize.com/api/v2/${event}/view/Sessions
8. https://sessionize.com/api/v2/${event}/view/Speakers

⁠Adjusting Event Dates and Times

The APUS_EVENT_DATE_ADJUST option uses the ISO-8601 period formats PnYnMnD and PnW. Examples:

The APUS_EVENT_TIME_ADJUST option uses the ISO-8601 duration formats PTnHnMnS. Examples:

⁠Create Mastodon Access Token

1. Please log in at https://YOUR.INSTANCE/⁠.
2. Open the page https://YOUR.INSTANCE/settings/applications/new⁠.
3. Fill out the form:
   • Application name: Apus
   • Application website: https://APUS_DOMAIN/
   • Adjust the permissions as follows:
     • Enable only "read:notifications"
     • Disable everything else
4. Scroll to the bottom and click "Save".
5. The new application "Apus" will now appear in the table.
6. Click on the name "Apus".
7. Copy the access token (third line).

Replace the placeholder YOUR.INSTANCE with the domain of the Mastodon instance where your account is registered (e.g. mastodon.social or ijug.social) and replace APUS_DOMAIN with the domain where your Apus installation is accessible (e.g. apus.ijug.eu).

⁠Custom Styles

You can modify the styles of the user interface using CSS variables. The CSS variables must be set using the environment variable APUS_STYLES in key and value pairs. The key is the variable to be set and must start with two dashes (--). Keys and values must be separated by a colon (:). Multiple key and value pairs are separated by a semicolon (;). Example:

--name-of-variable-one:value1;--name-of-variable-two:value2

The following table contains the CSS variables you can modify to change the user interface and their default values:

⁠Example Styles

⁠BaselOne

--event-background-color: #9a1445;
--event-title-color: #ffffff;
--event-text-color: #ffffff;
--event-running-session-color: #7248f0;
--event-next-session-color: #7248f0;
--event-closed-room-color: #7248f0;
--event-room-border: 1px solid #000000;
--event-image-border: 1px solid #000000;
--event-image-width: 250px;
--event-image-height: 250px;

--social-background-color: #7248f0;
--social-title-color: #ffffff;
--social-text-color: #000000;
--social-post-background-color: #ffffff;
--social-post-border: 1px solid #000000;

--speaker-avatar-background-color: transparent;
--speaker-avatar-border: none;

⁠Java Forum Stuttgart

--event-background-color: #fcb913;
--event-title-color: #000000;
--event-text-color: #000000;
--event-running-session-color: #fff8dd;
--event-next-session-color: #fff8dd;
--event-closed-room-color: #fff8dd;
--event-room-border: 1px solid #000000;
--event-image-border: 1px solid #000000;
--event-image-width: 852px;

--social-background-color: #fff8dd;
--social-title-color: #000000;
--social-text-color: #000000;
--social-post-background-color: #ffffff;
--social-post-border: 1px solid #fcb913;

⁠JavaLand

--event-running-session-color: #e1f1f2;
--event-running-session-border: 1px solid #36928f;
--event-next-session-color: #bde1e2;
--event-next-session-border: 1px solid #36928f;
--event-closed-room-color: #efe3f0
--event-closed-room-border: 1px solid #d479af;

--social-post-border: 1px solid #36928f;

⁠Voxxed Days Zürich

--event-background-color: #4c4f53;
--event-title-color: #8ed1fc;
--event-text-color: #000000;
--event-running-session-color: #ebfffc;
--event-next-session-color: #ebfffc;
--event-closed-room-color: #ebfffc;
--event-room-border: none;
--event-image-position-bottom: 10px;
--event-image-position-left: 10px;
--event-image-width: 425px;

--social-background-color: #58c3f0;
--social-title-color: #ffffff;
--social-text-color: #000000;
--social-post-background-color: #ebf7ff;
--social-post-border: none;

--speaker-avatar-background-color: transparent;
--speaker-avatar-border: none;

⁠Create Hashed Password

For security reasons the password is not stored in cleartext. Apus requires the password to be hashed using bcrypt⁠. Of course, Apus can do this for you. Start the JAR file providing the parameter -p followed by the password you want to create a hash for. The output will show you two lines of code. The first line contains the hashed password and the second line contains the same hashed password, but with the dollar signs escaped ready to copy and paste it into a docker-compose.yaml. Examples:

⁠Using the Command Line

java -jar apus.jar -p 12345
Hashed password for environment variable: $2a$10$nybQbl/iY8SRJkfHJVncS.L5.OC3KJ6VRBYVAID7qnUqwylmn/BtK
Hashed password for Docker Compose file: $$2a$$10$$nybQbl/iY8SRJkfHJVncS.L5.OC3KJ6VRBYVAID7qnUqwylmn/BtK

⁠Using Docker

docker run mcpringle/apus java -jar /usr/app/app.jar -p 12345
Hashed password for environment variable: $2a$10$nybQbl/iY8SRJkfHJVncS.L5.OC3KJ6VRBYVAID7qnUqwylmn/BtK
Hashed password for Docker Compose file: $$2a$$10$$nybQbl/iY8SRJkfHJVncS.L5.OC3KJ6VRBYVAID7qnUqwylmn/BtK

⁠Using Podman

podman run docker.io/mcpringle/apus java -jar /usr/app/app.jar -p 12345
Hashed password for environment variable: $2a$10$nybQbl/iY8SRJkfHJVncS.L5.OC3KJ6VRBYVAID7qnUqwylmn/BtK
Hashed password for Docker Compose file: $$2a$$10$$nybQbl/iY8SRJkfHJVncS.L5.OC3KJ6VRBYVAID7qnUqwylmn/BtK

⁠Configuration Files

All configuration files are completely optional and stored in an .apus subdirectory of the home directory of the user running Apus.

If you are running Apus in a Docker or Podman container and want to keep your configuration files between restarts, you can bind the .apus directory of the running container to an existing directory on your host system. Important: The directory on your host system must exist and must be writeable by the Apus user inside the container (which is user ID 1000 and group ID 1000). Consult the documentation of your host operating system if you need information about how to set the correct access rights.

Examples for binding the .apus directory of the running container to an existing directory on your host system using the -v option of Docker or Podman:

⁠Using Docker

docker run \
    --name apus \
    -p 80:8080 \
    -v $HOME/mydir:/home/apus/.apus \
    -e APUS_SOCIAL_HASHTAGS=java \
    -e APUS_TIMEZONE=Europe/Zurich \
    -d \
    --rm \
    mcpringle/apus

⁠Using Podman

podman run \
    --name apus \
    -p 80:8080 \
    -v $HOME/mydir:/home/apus/.apus \
    -e APUS_SOCIAL_HASHTAGS=java \
    -e APUS_TIMEZONE=Europe/Zurich \
    -d \
    --rm \
    docker.io/mcpringle/apus

⁠Communication

⁠Matrix Chat

There is a channel at Matrix for quick and easy communication. This is publicly accessible for everyone. For developers as well as users. The communication in this chat is to be regarded as short-lived and has no documentary character.

You can find our Matrix channel here: @project-apus:ijug.eu⁠

⁠GitHub Discussions

We use the corresponding GitHub function for discussions. The discussions held here are long-lived and divided into categories for the sake of clarity. One important category, for example, is that for questions and answers.

Discussions on GitHub: https://github.com/McPringle/apus/discussions⁠
Questions and Answers: https://github.com/McPringle/apus/discussions/categories/q-a⁠

⁠Copyright and License

AGPL License⁠

Copyright (C) Marcus Fihlon and the individual contributors to Apus.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see http://www.gnu.org/licenses/⁠.