falah-os-ce/docs/publish-to-istore.md

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

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

# 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:

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:

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

Then check:

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.