tipi/app-store
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update README.md

Browse Source
This commit is contained in:
Nicolas Meienberger 2022-08-17 20:52:41 +00:00 committed by GitHub
parent f71a615df8
commit ff6f52c027
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 1 additions and 177 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

178
README.md
View File

@ -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://<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
```
- 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)