From ff6f52c02762244938d0e29de204b20d0547b7d2 Mon Sep 17 00:00:00 2001 From: Nicolas Meienberger <47644445+meienberger@users.noreply.github.com> Date: Wed, 17 Aug 2022 20:52:41 +0000 Subject: [PATCH] Update README.md --- README.md | 178 +----------------------------------------------------- 1 file changed, 1 insertion(+), 177 deletions(-) diff --git a/README.md b/README.md index 9b32a46f..3495f5b4 100644 --- a/README.md +++ b/README.md @@ -43,180 +43,4 @@ This is the official repository for the Tipi App Store. It contains all the apps ## 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:///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/ -``` - -#### 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//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 -``` \ No newline at end of file +- Fork this repo and create the necessary files for a Tipi app. Follow this [guide](https://github.com/meienberger/runtipi/wiki/Contributing-to-Tipi#adding-your-own-app)