docs: write app submission guide
This commit is contained in:
Nicolas Meienberger
parent
739e01230a
commit
f71a615df8
17
.github/ISSUE_TEMPLATE/app-request.md
vendored
Normal file
17
.github/ISSUE_TEMPLATE/app-request.md
vendored
Normal file
|
|
@ -0,0 +1,17 @@
|
|||
---
|
||||
name: App Request
|
||||
about: Suggest an app to be added
|
||||
title: "[APP REQUEST]"
|
||||
labels: app request
|
||||
assignees: meienberger
|
||||
|
||||
---
|
||||
|
||||
**Describe app**
|
||||
A clear and concise description of what the app consists of and how it would benefit the users of Tipi.
|
||||
|
||||
**Links**
|
||||
Include links to all the available resources for the app. (eg: github repo, website, license)
|
||||
|
||||
**Additional context**
|
||||
Add any other context or screenshots about the app request here.
|
||||
222
README.md
Normal file
222
README.md
Normal file
|
|
@ -0,0 +1,222 @@
|
|||
# Tipi App Store
|
||||
This is the official repository for the Tipi App Store. It contains all the apps that are available for download on [Tipi](https://github.com/meienberger/runtipi).
|
||||
|
||||
## Apps available
|
||||
- [Adguard Home](https://github.com/AdguardTeam/AdGuardHome) - Adguard Home DNS adblocker
|
||||
- [Booksonic](https://github.com/popeen) - A server for streaming your audiobooks
|
||||
- [Calibre-Web](https://github.com/janeczku/calibre-web) - Web Ebook Reader
|
||||
- [Code-Server](https://github.com/coder/code-server) - Web VS Code
|
||||
- [Filebrowser](https://github.com/filebrowser/filebrowser) - Web File Browser
|
||||
- [Firefly III](https://github.com/firefly-iii/firefly-iii) - A personal finances manager
|
||||
- [Freshrss](https://github.com/FreshRSS/FreshRSS) - A free, self-hostable RSS aggregator
|
||||
- [Gitea](https://github.com/go-gitea/gitea) - Gitea - A painless self-hosted Git service
|
||||
- [Ghost](https://github.com/TryGhost/Ghost) - Ghost - Turn your audience into a business
|
||||
- [Homarr](https://github.com/ajnart/homarr) - A homepage for your server
|
||||
- [Home Assistant](https://github.com/home-assistant/core) - Open source home automation that puts local control and privacy first
|
||||
- [Invidious](https://github.com/iv-org/invidious) - An alternative front-end to YouTube
|
||||
- [Jackett](https://github.com/Jackett/Jackett) - API Support for your favorite torrent trackers
|
||||
- [Jellyfin](https://github.com/jellyfin/jellyfin) - A media server for your home collection
|
||||
- [Joplin](https://github.com/laurent22/joplin) - Privacy focused note-taking app
|
||||
- [Libreddit](https://github.com/spikecodes/libreddit) - Private front-end for Reddit
|
||||
- [Mealie](https://github.com/hay-kot/mealie) - Self-hosted recipe manager and meal planner.
|
||||
- [n8n](https://github.com/n8n-io/n8n) - Workflow Automation Tool
|
||||
- [Nextcloud](https://github.com/nextcloud/server) - A safe home for all your data
|
||||
- [Nitter](https://github.com/zedeus/nitter) - Alternative Twitter front-end
|
||||
- [Node-RED](https://github.com/node-red/node-red) - Low-code programming for event-driven applications
|
||||
- [Overseerr](https://github.com/sct/overseerr) - Request management and media discovery tool for the Plex ecosystem
|
||||
- [Photoprism](https://github.com/photoprism/photoprism) - AI-Powered Photos App for the Decentralized Web. We are on a mission to protect your freedom and privacy.
|
||||
- [Pihole](https://github.com/pi-hole/pi-hole) - A black hole for Internet advertisements
|
||||
- [Plex](https://github.com/plexinc/pms-docker) - Stream Movies & TV Shows
|
||||
- [Portainer](https://github.com/portainer/portainer) - Making Docker and Kubernetes management easy.
|
||||
- [Prowlarr](https://github.com/Prowlarr/Prowlarr/) - A torrent/usenet indexer manager/proxy
|
||||
- [Radarr](https://github.com/Radarr/Radarr) - Movie collection manager for Usenet and BitTorrent users
|
||||
- [Readarr](https://github.com/Readarr/Readarr) - Book Manager and Automation (Sonarr for Ebooks)
|
||||
- [Resilio Sync](https://github.com/bt-sync) - Fast, reliable, and simple file sync and share solution
|
||||
- [Sonarr](https://github.com/Sonarr/Sonarr) - TV show manager for Usenet and BitTorrent
|
||||
- [Syncthing](https://github.com/syncthing/syncthing) - Continuous File Synchronization
|
||||
- [Tailscale](https://github.com/tailscale/tailscale) - The easiest, most secure way to use WireGuard and 2FA
|
||||
- [Tautulli](https://github.com/Tautulli/Tautulli) - A Python based monitoring and tracking tool for Plex Media Server
|
||||
- [Transmission](https://github.com/transmission/transmission) - Fast, easy, and free BitTorrent client
|
||||
- [Wireguard Easy](https://github.com/WeeJeWel/wg-easy) - WireGuard VPN + Web-based Admin UI
|
||||
- [Vaultwarden](https://github.com/dani-garcia/vaultwarden) - Unofficial Bitwarden compatible server
|
||||
|
||||
## How to sumbit an app
|
||||
If you want to see new apps on Tipi you can either :
|
||||
- [Open an issue]() on this repository and some members of the community will add it
|
||||
- Fork this repo and create the necessary files for a Tipi app (guide below)
|
||||
|
||||
## Adding your own app
|
||||
> ⚠️ In order to proceed you should be familiar working with the Terminal and Git.
|
||||
#### Prerequisites
|
||||
- The app you want to add is free and open-source
|
||||
- The app you want to add has an official and maintained docker image
|
||||
|
||||
#### 1. Fork the repo
|
||||
In order to open a pull request you need to fork the repo. Start by clicking the "Fork" button in the upper right corner of this page.
|
||||
This will create a new repository with your name and an identical structure to the original repo.
|
||||
|
||||
#### 2. Clone the repo locally
|
||||
On your computer clone the repo you just forked.
|
||||
|
||||
```bash
|
||||
git clone https://<your-github-username>/meienberger/runtipi-appstore
|
||||
```
|
||||
|
||||
#### 3. Create a new branch for your app
|
||||
Navigate to the repoisitory you just cloned.
|
||||
|
||||
```bash
|
||||
cd runtipi-appstore
|
||||
```
|
||||
|
||||
Create a new branch for your app.
|
||||
|
||||
```bash
|
||||
git checkout -b app/<app-name>
|
||||
```
|
||||
|
||||
#### 4. Create the app files
|
||||
Each app requires at least the following files:
|
||||
- A `docker-compose.yml` file to run your app
|
||||
- A `config.json` file to configure your app
|
||||
- A description in markdown format
|
||||
- A logo in jpg format (512 x 512px)
|
||||
|
||||
Inside the repo open the `apps` folder and create a new folder for your app. The name should be the same as the app name without spaces or capital letters.
|
||||
|
||||
Create a new `config.json` file inside the newly create folder
|
||||
|
||||
```JSON
|
||||
{
|
||||
"name": "My super app",
|
||||
"available": true,
|
||||
"port": 8100,
|
||||
"id": "my-app", # This should be the same name as the folder
|
||||
"description": "", # Long description of the app
|
||||
"tipi_version": 1, # Always 1 if you are adding a new app
|
||||
"version": "1.25.1", # The actual version of the app (not the tipi version)
|
||||
"categories": ["utilities"], # One or more categories for the app
|
||||
"short_desc": "", # Short description of the app
|
||||
"author": "", # Link or name of the author
|
||||
"source": "", # Link for git repo
|
||||
"form_fields": [] # Used to ask for more info to the user before installing. Will be explained further
|
||||
}
|
||||
```
|
||||
|
||||
Available categories : `utilities`, `network`, `media`, `development`, `automation`, `social`, `utilities`, `photography`, `security`, `featured`, `books`, `data`, `music`, `finance`
|
||||
|
||||
If you want to add a new category, please open a new issue.
|
||||
|
||||
In the same folder, create a `docker-compose.yml` file with your app config.
|
||||
|
||||
```yml
|
||||
version: "3.9"
|
||||
services:
|
||||
my-app: # Should be exact same name as "id" field in config.json
|
||||
container_name: my-app # Should be exact same name as "id" field in config.json
|
||||
image: my-app:1.0.0 # Try to avoid "latest" tag. As it may break configs in the future.
|
||||
environment:
|
||||
- TZ=${TZ} # Can use any env variable. List in runtipi/templates/env-sample
|
||||
volumes:
|
||||
- ${APP_DATA_DIR}/data/config:/config # Always start the path with ${APP_DATA_DIR}. This will put all data inside app-data/my-app/data
|
||||
- ${APP_DATA_DIR}/data/projects:/projects
|
||||
ports:
|
||||
- ${APP_PORT}:8443
|
||||
restart: unless-stopped
|
||||
networks:
|
||||
- tipi_main_network
|
||||
```
|
||||
|
||||
You'll also need to create a `metadata` folder and inside put the following files:
|
||||
- `description.md` - Long description of the app in markdown format. (see previous apps for inspiration)
|
||||
- `logo.jpg` - Logo of the app in jpg format (512 x 512px)
|
||||
|
||||
#### 5. User defined environment variables
|
||||
Sometimes an app is requiring more info to run it such as passwords or username. You can leverage the `form_fields` property in the `config.json` file to ask such information. Let's take for example Nextcloud. The image requires a username and password. We can simply add two fields in the config.json that will be presented to the user before installing.
|
||||
|
||||
```JSON
|
||||
{
|
||||
...
|
||||
"form_fields": [
|
||||
{
|
||||
"type": "text",
|
||||
"label": "Username",
|
||||
"max": 50,
|
||||
"min": 3,
|
||||
"required": true,
|
||||
"env_variable": "NEXTCLOUD_ADMIN_USER"
|
||||
},
|
||||
{
|
||||
"type": "password",
|
||||
"label": "Password",
|
||||
"max": 50,
|
||||
"min": 3,
|
||||
"required": true,
|
||||
"env_variable": "NEXTCLOUD_ADMIN_PASSWORD"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
You can choose between different types of fields. The app will automatically validate the user input before submitting.
|
||||
|
||||
| Type | Description | Example value |
|
||||
|--------------|-----------------|------------|
|
||||
| **text** | Just a string of text | username |
|
||||
| **password** | Will be hidden on typing | password |
|
||||
| **email** | An email address | test@example.org |
|
||||
| **number** | Any number | 123 |
|
||||
| **fqdn** | Fully qualified domain name | example.org |
|
||||
| **ip** | Any valid ipv4 address | 192.168.2.100 |
|
||||
| **fqdnip** | Combination between ip and fqdn | 192.168.2.100 or example.org |
|
||||
| **random** | Generate a random value for the user | 2m3ffc0923rk93df9023f9 |
|
||||
|
||||
You can also define a min and max length of input with the corresponding properties.
|
||||
The `env_variable` property is the name of the variable you'll use in your `docker-compose.yml` file. Be sure to have a unique name.
|
||||
|
||||
So if we take the Nextcloud example again, this is how you would use the `form_fields` inside your compose file.
|
||||
|
||||
```yml
|
||||
version: "3.7"
|
||||
|
||||
services:
|
||||
nextcloud:
|
||||
container_name: nextcloud
|
||||
image: nextcloud:23.0.3-apache
|
||||
restart: unless-stopped
|
||||
ports:
|
||||
- ${APP_PORT}:80
|
||||
volumes:
|
||||
- ${APP_DATA_DIR}/data/nextcloud:/var/www/html
|
||||
environment:
|
||||
- NEXTCLOUD_ADMIN_USER=${NEXTCLOUD_ADMIN_USER}
|
||||
- NEXTCLOUD_ADMIN_PASSWORD=${NEXTCLOUD_ADMIN_PASSWORD}
|
||||
```
|
||||
|
||||
`NEXTCLOUD_ADMIN_USER` and `NEXTCLOUD_ADMIN_PASSWORD` are coming from the user inputs.
|
||||
|
||||
#### 6. Default data folder
|
||||
If your app requires default files or configuration, you can easily provide those by creating a `data` folder beside the app config.
|
||||
|
||||
```
|
||||
├── apps
|
||||
|-- my-app
|
||||
|-- config.json
|
||||
|-- data
|
||||
| |-- anything.conf
|
||||
|-- docker-compose.yml
|
||||
|-- metadata
|
||||
|-- description.md
|
||||
|-- logo.jpg
|
||||
```
|
||||
|
||||
Anything placed under data will be copied over `app-data/<app-id>/data`
|
||||
Then you can mount those files inside your compose file.
|
||||
|
||||
```yml
|
||||
my-app:
|
||||
container_name: my-app
|
||||
restart: unless-stopped
|
||||
volumes:
|
||||
- ${APP_DATA_DIR}/data:/var/lib/config # Will mount the folder with `anything.conf` inside
|
||||
```
|
||||
|
|
@ -1,4 +1,4 @@
|
|||
version: "3.7"
|
||||
version: "3.9"
|
||||
|
||||
networks:
|
||||
tipi_main_network:
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user