Create your own app store

Use the repository template

First, head over to the Runtipi app store template repository  and click the “Use this template” button to create a new repository based on the template. This will give you a starting point with the necessary structure and files.

Give your new repository a meaningful name and make sure to set it as a public repository.

Add your new store to Runtipi

Grab the URL of your new repository. It should look something like this:

https://github.com/<your-username>/<your-store-name>

Head over to your Runtipi instance and navigate to the settings page. Click on “App Stores” and then “Add App Store”.

Paste the URL of your new repository and give it a name. This name will be used to identify the app store in the Runtipi dashboard.

You should see your new app store listed in the app stores section with the default Whoami app.

Create your first app

First, clone your new repository to your local machine:

git clone <your-repo-url>

Open the cloned repository in your favorite code editor. Inside the apps directory, you’ll find a sample app called whoami. You can use this as a template for your own apps. Each app should be in its own folder inside the apps directory. The folder name should match the app’s ID in the config.json file. For each app, you’ll need:

1. A config.json file with app metadata (name, description, version, etc.)
2. A docker-compose.json file defining the app’s services using the dynamic compose format
3. A metadata folder containing at least a logo.jpg image and a description.md file

We will add Nginx as an example app.

First create a new folder in the apps directory called nginx. Inside this folder, create two files: docker-compose.json and config.json.

Here’s the docker-compose.json

{
  "services": [
    {
      "name": "nginx",
      "image": "nginx:1.25.3",
      "isMain": true,
      "internalPort": 80
    }
  ]
}

And it’s corresponding config.json:

{
  "name": "Nginx",
  "available": true,
  "port": 8754,
  "exposable": true,
  "dynamic_config": true,
  "id": "nginx",
  "description": "Simple webserver to test your tipi install. An alternative to the hello-world app.",
  "tipi_version": 3,
  "version": "1.25.3",
  "categories": ["utilities"],
  "short_desc": "Open-source simple and fast web server.",
  "author": "nginx",
  "source": "https://github.com/nginx/nginx",
  "website": "https://www.nginx.com/",
  "form_fields": [],
  "supported_architectures": ["arm64", "amd64"],
  "created_at": 1691943801422,
  "updated_at": 1729872794208
}

Add a description.md file in the metadata folder with a description of your app. This will be displayed in the Runtipi dashboard. Add a logo.jpg image in the metadata folder. This will be used as the app’s icon in the Runtipi dashboard. Use a square image with a 1:1 aspect ratio.

The final folder structure should look like this:

• my-store
  • apps
    • nginx
      • metadata
        • description.md
        • logo.jpg
    • config.json
    • docker-compose.json

Commit and push your repository

Once you’ve added your app, create a new branch and commit your changes:

git checkout -b add-nginx-app
git add .
git commit -m "Add Nginx app"
git push -u origin add-nginx-app

Create a pull request

Head over to your GitHub repository and create a pull request. This will allow you to review your changes before merging them into the main branch. A default test suite will run to check that your app is valid and follows the Runtipi app store file format.

Once the tests pass, you can merge your pull request into the main branch.

Test your new app

Go to the Runtipi settings page and click on the “Update App Stores” button. This will pull the latest changes from your repository and update the app store. You can now try to install your new app.