Antigravity AI
d210e5d8c5
- docs/publish-to-istore.md: full app.yml spec, Docker image requirements, and step-by-step publishing workflow for developers - .env.example: document pre-generated Gitea token scope and bitwarden.falahos.my retrieval note Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JWCfXRGY3WA5PNeMRLad7w
107 lines
3.6 KiB
Markdown
107 lines
3.6 KiB
Markdown
# 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.
|