Skip to content

Adding your own app

Jump to bottom
Nicolas Meienberger edited this page Aug 17, 2022 · 3 revisions

⚠️ 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. Visit the official App Store repo and start by clicking the "Fork" button in the upper right corner of the 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.

git clone https://<your-github-username>/meienberger/runtipi-appstore

3. Create a new branch for your app

Navigate to the repoisitory you just cloned.

cd runtipi-appstore

Create a new branch for your app.

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

{
  "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.

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 other 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.

{
  ...
  "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.

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.

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

7. Commit your changes

Once you're done, you can commit your changes to the repository.

git add .
git commit -m "Add my-app"
git push origin master

8. Submit a Pull Request

You can now submit a pull request to the repository.

  • On GitHub, visit your repository and click on the "Pull requests" tab.
  • Click on "New pull request" and fill in the title and description.
  • Choose your branch and target the main repository at meienberger/runtipi-appstore.
Clone this wiki locally