# Publishing an App to Falah OS iStore

Any developer can publish an app to the iStore by creating a public repository in the
`falahos` organization on [git.falahos.my](https://git.falahos.my/falahos) and adding
an `app.yml` manifest at the repository root.

---

## 1. Request org membership

Contact the Falah OS team to be added as a member of the `falahos` org on Gitea.
Once added you can create repositories directly in the org.

## 2. Create your app repository

Repository naming convention: `app-<your-app-id>` (e.g. `app-prayer-times`).

```bash
# via Gitea UI: git.falahos.my → + → New Repository → Owner: falahos
# or via API:
curl -X POST https://git.falahos.my/api/v1/orgs/falahos/repos \
  -H "Authorization: token $YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"app-my-app","private":false,"auto_init":true}'
```

## 3. Add `app.yml` at the repository root

The iStore service reads this file to populate the store listing.

```yaml
# app.yml — required fields
id: my-app                          # unique, kebab-case, matches repo name suffix
name: My App                        # display name
version: 1.0.0                      # semver
tagline: One-line description       # shown in store card
category: Finance                   # Finance | Worship | Lifestyle | Productivity | Tools
ramz_verified: false                # true = Ramz-audited Islamic finance compliance
image: docker.io/yourorg/my-app:latest   # Docker image to pull on install
port: 8080                          # host port the container exposes
icon: 🕌                            # emoji or URL to 512×512 PNG
featured: false                     # request featured placement (reviewed by team)
author: Your Name / Org
license: MIT                        # SPDX identifier
min_ce_version: 1.3                 # minimum Falah OS CE version required
```

## 4. Publish your Docker image

The App Manager pulls the `image` value directly from the manifest.
Push to any public registry your CE instance can reach:

```bash
docker build -t docker.io/yourorg/my-app:1.0.0 .
docker push docker.io/yourorg/my-app:1.0.0
docker tag  docker.io/yourorg/my-app:1.0.0 docker.io/yourorg/my-app:latest
docker push docker.io/yourorg/my-app:latest
```

## 5. Verify the listing

Once your `app.yml` is on the `main` branch the iStore will pick it up within
5 minutes (cache TTL). You can force a refresh:

```bash
curl -X POST http://<ce-host>:3021/api/cache/clear
```

Then check:

```bash
curl http://<ce-host>:3021/api/apps/<your-app-id>
```

---

## App manifest reference

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `id` | string | ✅ | kebab-case, unique |
| `name` | string | ✅ | display name |
| `version` | string | ✅ | semver |
| `tagline` | string | ✅ | ≤ 80 chars |
| `category` | string | ✅ | see allowed values above |
| `ramz_verified` | bool | ✅ | `true` only after audit |
| `image` | string | ✅ | fully-qualified Docker image |
| `port` | int | ✅ | container port to expose |
| `icon` | string | ✅ | emoji or HTTPS PNG URL |
| `featured` | bool | — | default `false` |
| `author` | string | — | |
| `license` | string | — | SPDX id |
| `min_ce_version` | string | — | semver |

## Container requirements

Your Docker container must:

- Listen on the port declared in `app.yml`
- Start within 30 seconds
- Respond to `GET /health` with HTTP 200 (optional but recommended)
- Run as a non-root user where possible
- Not require host-mode networking

The App Manager places each installed container on the `falah-net` Docker network,
so containers can reach each other by service name.