Compare commits
12
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
55f232e172 | ||
|
|
1f23ea1d78 | ||
|
|
a705a49495 | ||
|
|
5c23ec9310 | ||
|
|
b39c9b9289 | ||
|
|
f2e74564df | ||
|
|
03d32d2356 | ||
|
|
2ccf793644 | ||
|
|
b0edbf2c33
|
||
|
|
0896699581 | ||
|
|
606bfc5660 | ||
|
|
1ec63c443b |
No files matched your search
+22
-40
@@ -1,33 +1,25 @@
|
|||||||
# Woodpecker CI pipeline for co-op/docs — THIN on purpose.
|
# Woodpecker CI pipeline for co-op/docs — THIN and SECRET-FREE on purpose.
|
||||||
#
|
#
|
||||||
# It does NOT re-implement the build. The repository's publishing layer is the
|
# It does NOT deploy. Publishing is host-side and split:
|
||||||
# single source of truth and this pipeline only wires it up:
|
|
||||||
#
|
#
|
||||||
# publishing/requirements.txt pinned MkDocs + Material toolchain
|
# /usr/local/sbin/docs-poll host-owned poller (root) — pulls main
|
||||||
# publishing/build.sh stage Markdown -> .site-src/, render .site-build/
|
# publishing/build.sh runs as the unprivileged `docsbuild` user,
|
||||||
# publishing/deploy.sh push .site-build/ into the Cloudron Surfer app
|
# with no credentials and no access to
|
||||||
|
# /home/ubuntu
|
||||||
|
# /usr/local/sbin/docs-publish root-owned publish step — runs no repo code,
|
||||||
|
# holds the Cloudron token from a root-only file
|
||||||
#
|
#
|
||||||
# Any change to how the site is built belongs in publishing/, never here.
|
# CI exists only to prove the repository builds. It runs in a throwaway venv
|
||||||
|
# inside the pipeline workspace, never the agent image's shared /opt/docs-venv:
|
||||||
|
# a push to ANY repo must not be able to change a toolchain that another
|
||||||
|
# pipeline uses. No secret is wired into this pipeline, and none should be
|
||||||
|
# until the Woodpecker agent supports per-pipeline isolation.
|
||||||
#
|
#
|
||||||
# Run model: MANUAL ONLY for now. The Gitea webhook that fires this on push is
|
# Backend note: the co-op's Woodpecker agent is a Cloudron app with no Docker
|
||||||
# deliberately NOT wired — the poll watcher (docs-deploy-poll.service on the
|
# socket, so it uses Woodpecker's `local` backend. Each step runs as a shell
|
||||||
# agent host) remains the live auto-deploy path until a manual run has proven
|
# command INSIDE the agent container; the `image:` field selects the SHELL, not
|
||||||
# the pipeline. Once it has, add `push` to the `when` block below and register
|
# a container image. That is exactly why this file must stay secret-free: the
|
||||||
# the webhook in Gitea.
|
# container is shared by every pipeline.
|
||||||
#
|
|
||||||
# Backend note (IMPORTANT — this is why there are no container images here):
|
|
||||||
# The co-op's Woodpecker agent runs as a Cloudron app, which has no Docker
|
|
||||||
# socket, so it uses Woodpecker's `local` backend. Under `local` each step is
|
|
||||||
# run as a shell command INSIDE the agent container, and the step's `image:`
|
|
||||||
# field selects the SHELL, not a container image. Every tool the steps need is
|
|
||||||
# therefore baked into the agent image (co-op/woodpecker-agent):
|
|
||||||
# python3 + the pinned MkDocs toolchain (venv at /opt/docs-venv, mirroring
|
|
||||||
# publishing/requirements.txt), node + the cloudron CLI, bash, git, tar.
|
|
||||||
# If the toolchain pin changes, rebuild that image — see its Dockerfile.
|
|
||||||
#
|
|
||||||
# Secrets required (Woodpecker repo secret, name `cloudron_token`):
|
|
||||||
# cloudron_token = the Cloudron API token used by publishing/deploy.sh
|
|
||||||
# Do not put credentials in this file.
|
|
||||||
|
|
||||||
when:
|
when:
|
||||||
- event: manual
|
- event: manual
|
||||||
@@ -36,17 +28,7 @@ steps:
|
|||||||
- name: build
|
- name: build
|
||||||
image: bash
|
image: bash
|
||||||
commands:
|
commands:
|
||||||
# Reuses the toolchain pre-installed in the agent image; build.sh only
|
# Ephemeral toolchain per run — no shared venv, no /opt/docs-venv.
|
||||||
# creates/installs a venv if the one given is missing, which it is not.
|
- python3 -m venv .ci-venv
|
||||||
- publishing/build.sh /opt/docs-venv
|
- .ci-venv/bin/pip install -q -r publishing/requirements.txt
|
||||||
|
- publishing/build.sh .ci-venv
|
||||||
- name: deploy
|
|
||||||
image: bash
|
|
||||||
commands:
|
|
||||||
# deploy.sh drives the Cloudron `cloudron` CLI (a node program) via
|
|
||||||
# `cloudron exec`; node, the CLI, bash, git and tar are all in the agent
|
|
||||||
# image. The build it publishes is the shared workspace .site-build/.
|
|
||||||
- publishing/deploy.sh
|
|
||||||
environment:
|
|
||||||
CLOUDRON_TOKEN:
|
|
||||||
from_secret: cloudron_token
|
|
||||||
@@ -43,7 +43,7 @@ Your **chat history is stored on our server** so you can revisit past conversati
|
|||||||
|
|
||||||
We commit not to read it. But this is a **policy commitment**, not an architectural guarantee. We're transparent about this distinction because it matters.
|
We commit not to read it. But this is a **policy commitment**, not an architectural guarantee. We're transparent about this distinction because it matters.
|
||||||
|
|
||||||
Note the boundary precisely: enclave models protect your conversation **while it is being processed** — the model provider and we cannot read the exchange at inference time. Stored history is a separate leg: once a conversation is saved, it sits on our server in a form we can technically read. So for sensitive material, the strongest combination available today is a **Temporary Chat with an enclave model** — protected in transit and at inference, and never stored afterwards.
|
Note the boundary precisely: enclave models protect your conversation **while it is being processed** — the model provider and we cannot read the exchange at inference time. Stored history is a separate leg: once a conversation is saved, it sits on our server in a form we can technically read. So for sensitive material, the strongest combination available today is a **Temporary Chat with an enclave model** — protected in transit and at inference, and deleted shortly afterwards.
|
||||||
|
|
||||||
### If you use the API, nothing you send is stored
|
### If you use the API, nothing you send is stored
|
||||||
|
|
||||||
@@ -71,7 +71,7 @@ it is:
|
|||||||
|
|
||||||
The chat has a **Temporary Chat** mode designed exactly for this:
|
The chat has a **Temporary Chat** mode designed exactly for this:
|
||||||
|
|
||||||
- Click the **Temporary Chat** toggle in the chat header, and the conversation is **never saved** — it doesn't appear in your history, it isn't written to our database, and it disappears when you leave the page.
|
- Click the **Temporary Chat** toggle in the chat header, and the conversation is hidden from your history. It still exists on our server while you use it, so the chat can work; we retain temporary chats as minimally as possible and delete them automatically shortly after creation. It may remain in encrypted backups until those backups age out. Details are in [Infrastructure](../operations/infrastructure.md#chat-retention-and-web-search).
|
||||||
- To make this the default for every new conversation, open **Settings → Conversations** and enable **Default Temporary Chat**. The preference is stored in your browser, so it's yours to change at any time.
|
- To make this the default for every new conversation, open **Settings → Conversations** and enable **Default Temporary Chat**. The preference is stored in your browser, so it's yours to change at any time.
|
||||||
- The trade-off is that there's nothing to revisit: no history, no search, no sync across devices. Use it whenever that trade is right for you — you can mix saved and temporary conversations freely.
|
- The trade-off is that there's nothing to revisit: no history, no search, no sync across devices. Use it whenever that trade is right for you — you can mix saved and temporary conversations freely.
|
||||||
|
|
||||||
@@ -83,13 +83,31 @@ Our server software keeps standard operational logs (dates, error messages, and
|
|||||||
|
|
||||||
## 5. Search
|
## 5. Search
|
||||||
|
|
||||||
Web search runs through our self-hosted search instance. Search queries are forwarded to the underlying search engines (e.g. DuckDuckGo), which may see them. This is inherent to how web search works.
|
Our self-hosted **SearXNG** instance at
|
||||||
|
[search.inference.coop](https://search.inference.coop) handles web search. For
|
||||||
|
chat searches it forwards queries to **DuckDuckGo** and **Brave**; those
|
||||||
|
services receive the query from our server and may see it. Search queries and
|
||||||
|
results are part of the conversation record, so they follow that conversation's
|
||||||
|
retention: deleted when you delete a saved chat, or about an hour after a
|
||||||
|
Temporary Chat is created. Operational details are in
|
||||||
|
[Infrastructure](../operations/infrastructure.md#chat-retention-and-web-search).
|
||||||
|
|
||||||
|
To read the pages behind the results, our own page-fetch service fetches the
|
||||||
|
top result URLs. It runs on co-op infrastructure at fetch.inference.coop. The
|
||||||
|
service does not log the URLs or the page text and keeps no copy: the extracted
|
||||||
|
text goes to the model for that answer and is not stored by the fetcher. It
|
||||||
|
refuses private, loopback, and internal addresses, so it cannot be used to reach
|
||||||
|
our own network. Your chat messages and account identity stay with us.
|
||||||
|
|
||||||
|
Web search is optional. Leave the globe off for sensitive topics. Note that the
|
||||||
|
search engines in §7 still receive your query when you use it.
|
||||||
|
|
||||||
## 6. What we do NOT do
|
## 6. What we do NOT do
|
||||||
|
|
||||||
- We do **not** train models on your data.
|
- We do **not** train models on your data.
|
||||||
- We do **not** sell, rent, or share your data.
|
- We do **not** sell or rent your data.
|
||||||
- We do **not** use your data for advertising or profiling.
|
- We do **not** share data for advertising or profiling. The service providers
|
||||||
|
in §5 and §7 process data to run the service.
|
||||||
|
|
||||||
## 7. Third parties
|
## 7. Third parties
|
||||||
|
|
||||||
@@ -97,12 +115,13 @@ The models we serve are provided by third parties that change over time, each wi
|
|||||||
|
|
||||||
- **Open Collective** — handles billing and membership (their own privacy policy applies).
|
- **Open Collective** — handles billing and membership (their own privacy policy applies).
|
||||||
- **Cloudron** — our self-hosted platform; no third-party cloud provider.
|
- **Cloudron** — our self-hosted platform; no third-party cloud provider.
|
||||||
- **Search engines** — receive your search queries (see §5).
|
- **Search engines.** DuckDuckGo and Brave receive your search queries (see §5).
|
||||||
|
Page fetching runs on co-op infrastructure, not at a third party.
|
||||||
|
|
||||||
## 8. Retention and deletion
|
## 8. Retention and deletion
|
||||||
|
|
||||||
- Chat history is retained until you delete it.
|
- Chat history is retained until you delete it.
|
||||||
- **Temporary chats are never retained** — they are not written to our database at all (see §4).
|
- **Temporary chats are retained as minimally as possible** — hidden from history immediately and deleted automatically shortly after creation. Details are in [Infrastructure](../operations/infrastructure.md#chat-retention-and-web-search).
|
||||||
- On leaving, your account is deactivated (data preserved for reactivation).
|
- On leaving, your account is deactivated (data preserved for reactivation).
|
||||||
- You may request full deletion at any time: info@inference.coop.
|
- You may request full deletion at any time: info@inference.coop.
|
||||||
|
|
||||||
@@ -110,7 +129,8 @@ The models we serve are provided by third parties that change over time, each wi
|
|||||||
|
|
||||||
- Self-hosted on Cloudron (sandboxed apps, SSL, backups).
|
- Self-hosted on Cloudron (sandboxed apps, SSL, backups).
|
||||||
- Per-member API keys; access gated on live membership.
|
- Per-member API keys; access gated on live membership.
|
||||||
- No external dependencies for core infrastructure.
|
- Core infrastructure has no external dependencies. Web search sends queries
|
||||||
|
to the search engines named in §5; page fetching runs on co-op infrastructure.
|
||||||
|
|
||||||
## 10. Your rights
|
## 10. Your rights
|
||||||
|
|
||||||
|
|||||||
@@ -56,8 +56,10 @@ with the account you created in step 1.
|
|||||||
(GreenPT and Regolo, 100% renewable energy — Regolo adds a written
|
(GreenPT and Regolo, 100% renewable energy — Regolo adds a written
|
||||||
zero-data-retention policy). See the [model list](models.md) for the full
|
zero-data-retention policy). See the [model list](models.md) for the full
|
||||||
list.
|
list.
|
||||||
- **Web search** — click the **globe** next to the message box to ground
|
- **Web search.** Click the **globe** next to the message box to base answers
|
||||||
answers in current web results (self-hosted search, no external dependency).
|
on current web results. Searches use our self-hosted SearXNG instance, and
|
||||||
|
pages are read by our own fetcher. See [what happens during a
|
||||||
|
search](#what-happens-when-you-use-web-search).
|
||||||
- **File uploads** — attach a document with the **paperclip** and ask the
|
- **File uploads** — attach a document with the **paperclip** and ask the
|
||||||
chat about it.
|
chat about it.
|
||||||
- **Tools** — the **Tools menu** next to the message box lists everything the
|
- **Tools** — the **Tools menu** next to the message box lists everything the
|
||||||
@@ -84,6 +86,22 @@ see "Your allowance" below.
|
|||||||
> — your full history is here in the new chat, but files you attached in the
|
> — your full history is here in the new chat, but files you attached in the
|
||||||
> old one are still accessible only there.
|
> old one are still accessible only there.
|
||||||
|
|
||||||
|
### What happens when you use web search
|
||||||
|
|
||||||
|
Web search runs in two stages.
|
||||||
|
|
||||||
|
1. Our self-hosted **SearXNG** instance at
|
||||||
|
[search.inference.coop](https://search.inference.coop) sends your query to
|
||||||
|
**DuckDuckGo** and **Brave**.
|
||||||
|
2. LibreChat sends the top result URLs to the co-op's **own page fetcher**. It
|
||||||
|
reads each page and extracts its text. The model receives those passages,
|
||||||
|
and the answer cites the sources.
|
||||||
|
|
||||||
|
Both SearXNG and the page fetcher run on co-op infrastructure. The fetcher does
|
||||||
|
not log the URLs or the page text and keeps no copy. The
|
||||||
|
[privacy policy](../governance/privacy-policy.md#5-search) describes this. Web
|
||||||
|
search is optional. Leave the globe off if you do not want pages fetched.
|
||||||
|
|
||||||
### Add the chat to your phone
|
### Add the chat to your phone
|
||||||
|
|
||||||
The chat works like an app on your phone — no app store needed. Open
|
The chat works like an app on your phone — no app store needed. Open
|
||||||
|
|||||||
@@ -0,0 +1,200 @@
|
|||||||
|
# Using the co-op privately on your phone or computer
|
||||||
|
|
||||||
|
## Why use a local app
|
||||||
|
|
||||||
|
*A step-by-step walkthrough for members who aren't developers/super technical. Whole process takes about 15 minutes. Drafted for [co-op/support#56](https://git.inference.coop/co-op/support/issues/56).*
|
||||||
|
|
||||||
|
The co-op's web chat keeps your conversation history on the co-op's server. If you'd rather keep that history on your own phone or computer, you can talk to the same co-op models from a chat app installed on your device. Any app that accepts a custom "OpenAI-compatible" connection will work. This guide uses two free examples: **Jan** for computers and **Chatbox** for phones and computers.
|
||||||
|
|
||||||
|
> **What changes, and what doesn't**
|
||||||
|
>
|
||||||
|
> - **Changes:** your chat history is saved on your device, not on the co-op's server.
|
||||||
|
> - **Doesn't change:** every message still travels through the co-op's gateway to the model provider (Tinfoil, GreenPT or Regolo), exactly as in the web chat. The co-op records usage (which model, how many tokens, the cost), not what you wrote.
|
||||||
|
> - **You give up:** the web chat's document search and image tool, and history that syncs between your devices. Each device keeps its own chats.
|
||||||
|
|
||||||
|
### Which app should I use?
|
||||||
|
|
||||||
|
| | Jan | Chatbox |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| Runs on | Mac (Apple silicon), Windows, Linux | iPhone, iPad, Android, Mac, Windows, Linux |
|
||||||
|
| Connecting to the co-op | Finds the co-op's models for you | You may need to type model names in |
|
||||||
|
| Running open models on your own computer | Built in | Needs a separate app |
|
||||||
|
| Cost | Free, no paid plans | Free with your co-op key; also sells its own optional plans |
|
||||||
|
| Open source | Yes, Apache 2.0 | Community Edition is GPL-3.0 |
|
||||||
|
|
||||||
|
**Rule of thumb:** on a phone, use Chatbox. On a computer, either works; Jan is a little easier to connect.
|
||||||
|
|
||||||
|
### What you need
|
||||||
|
|
||||||
|
- A phone, tablet or computer from the table above
|
||||||
|
- An email address
|
||||||
|
- A card or account you can pay dues with on Open Collective
|
||||||
|
- About 15 minutes
|
||||||
|
|
||||||
|
## Part 1. Join the co-op (everyone)
|
||||||
|
|
||||||
|
### Step 1. Become a member
|
||||||
|
|
||||||
|
1. Go to [inference.coop](https://inference.coop) and click **Become a member**.
|
||||||
|
2. Open Collective opens with $5/month filled in. Dues are a sliding scale: pay $5, or more if you can. Every member gets the same $15 of usage each month, whatever they pay.
|
||||||
|
3. Finish the checkout.
|
||||||
|
|
||||||
|
> **Important:** use the same email address here that you'll use for your co-op login. That's how the co-op knows you're a member.
|
||||||
|
|
||||||
|
### Step 2. Create your co-op login
|
||||||
|
|
||||||
|
1. Within a few minutes you'll get a **welcome email**. Check spam if it doesn't arrive.
|
||||||
|
2. Click the link in it and create your username and password.
|
||||||
|
|
||||||
|
You can now log in to the web chat and the Member Dashboard.
|
||||||
|
|
||||||
|
### Step 3. Make your API key
|
||||||
|
|
||||||
|
An **API key** is a long password that lets an app use your membership. It starts with `sk-`.
|
||||||
|
|
||||||
|
1. Go to [dashboard.inference.coop](https://dashboard.inference.coop) and log in.
|
||||||
|
2. Find the API keys section and create a new key. Give it a name you'll recognise, like `Jan_on_my_laptop` or `Chatbox_on_my_phone`. A separate key for each device lets you switch one off without affecting the others.
|
||||||
|
3. **Copy the key now** and keep it somewhere safe, such as your password manager.
|
||||||
|
|
||||||
|
> **Treat the key like a password.** Anyone who has it can spend your monthly allowance. Don't paste it into email, chat or shared documents. If it leaks, delete it in the dashboard and make a new one.
|
||||||
|
|
||||||
|
Now continue with [Part 2A for Jan](#part-2a-jan-on-a-computer) or [Part 2B for Chatbox](#part-2b-chatbox-on-a-phone-or-computer).
|
||||||
|
|
||||||
|
## Part 2A. Jan on a computer
|
||||||
|
|
||||||
|
### Jan step 4. Install Jan
|
||||||
|
|
||||||
|
1. Go to [jan.ai](https://jan.ai) and download Jan for your computer.
|
||||||
|
2. **Mac:** open the downloaded `.dmg` file and drag Jan into Applications. **Windows:** run the `.exe` installer. **Linux:** use the Flatpak (`flatpak install flathub ai.jan.Jan`) or the `.deb`/AppImage.
|
||||||
|
3. Open Jan. On first launch it asks whether to share anonymous usage data. It's off unless you say yes; choose whichever you prefer.
|
||||||
|
|
||||||
|
Jan is free and open source (Apache 2.0). You don't need a Jan account.
|
||||||
|
|
||||||
|
### Jan step 5. Connect Jan to the co-op
|
||||||
|
|
||||||
|
1. In Jan, open **Settings** (the gear), then **Model Providers**.
|
||||||
|
2. Click **Add Provider**.
|
||||||
|
3. Fill in the **Add Custom Provider** box exactly like this:
|
||||||
|
|
||||||
|
| Field | What to enter |
|
||||||
|
| --- | --- |
|
||||||
|
| API format | **OpenAI-compatible** |
|
||||||
|
| Provider name | `Inference Co-op` |
|
||||||
|
| Base URL | `https://gateway.inference.coop/v1` |
|
||||||
|
| API key | your `sk-…` key from Step 3 |
|
||||||
|
|
||||||
|
4. Click **Create**.
|
||||||
|
|
||||||
|
Jan now asks the co-op which models you can use and lists them under the new provider. If the list is empty, click the **refresh** icon next to **Models**.
|
||||||
|
|
||||||
|
> **Check the Base URL.** It must end in `/v1`, with nothing after it. Don't add `/chat/completions`.
|
||||||
|
|
||||||
|
### Jan step 6. Turn on tool access
|
||||||
|
|
||||||
|
Jan can't tell what each co-op model is able to do, so it treats every co-op model as plain chat. Until you switch on **Tools**, a model can't use Jan's web search or other tools, even when it wants to. When that happens, the reply can get stuck repeating "Let me search the web…" over and over.
|
||||||
|
|
||||||
|
1. Go to **Settings → Model Providers → Inference Co-op**.
|
||||||
|
2. Click the **pencil** next to a model you plan to use.
|
||||||
|
3. Under **Capabilities**, switch on **Tools**. Switch on **Vision** too if the model can read images.
|
||||||
|
4. Repeat for each model you use. The [model table](#which-model-should-i-use) shows which models support what.
|
||||||
|
|
||||||
|
### Jan step 7. Say hello
|
||||||
|
|
||||||
|
1. Start a **New Chat**.
|
||||||
|
2. Click the model name above the message box and choose a model under **Inference Co-op**. Not sure? Start with `deepseek-flash-green`, the web chat's default. A **tools** label next to a model means step 6 worked.
|
||||||
|
3. **Optional: let it search the web.** Click the **globe icon** in the toolbar under the message box. It reads **Web Search (Active)** when on. Only models with Tools switched on can use it.
|
||||||
|
4. Type a message and press Enter.
|
||||||
|
|
||||||
|
If an answer comes back, you're done. Your conversation is saved on your computer, in Jan.
|
||||||
|
|
||||||
|
> **Where your searches go.** Jan's web search doesn't run through the co-op. By default it uses a search service called Exa, which needs no key. You can choose a different service in **Settings → Web Search**.
|
||||||
|
|
||||||
|
## Part 2B. Chatbox on a phone or computer
|
||||||
|
|
||||||
|
### Chatbox step 4. Install Chatbox
|
||||||
|
|
||||||
|
1. **iPhone or iPad:** search for *Chatbox AI* in the App Store. **Android:** search in Google Play, or download the APK from [chatboxai.app](https://chatboxai.app). **Mac, Windows, Linux:** download the installer from [chatboxai.app](https://chatboxai.app).
|
||||||
|
2. Open Chatbox.
|
||||||
|
3. If it offers to sign you up for **Chatbox AI**, skip it. That's Chatbox's own paid model service. You don't need an account or a plan to use your co-op key.
|
||||||
|
|
||||||
|
> **Two kinds of AI in one app.** Chatbox sells its own models (Lite, Pro and Pro+ plans). This guide uses only the co-op's models, paid for by your membership. When you pick a model, make sure it's one listed under your co-op provider.
|
||||||
|
|
||||||
|
### Chatbox step 5. Connect Chatbox to the co-op
|
||||||
|
|
||||||
|
1. Open **Settings**, then **Model Provider**. On a phone, Settings is in the side menu.
|
||||||
|
2. Scroll to the bottom and tap **Add**.
|
||||||
|
3. Fill it in exactly like this:
|
||||||
|
|
||||||
|
| Field | What to enter |
|
||||||
|
| --- | --- |
|
||||||
|
| Name | `Inference Co-op` |
|
||||||
|
| API mode | **OpenAI API Compatible** |
|
||||||
|
| API Host | `https://gateway.inference.coop/v1` |
|
||||||
|
| API Path | leave empty |
|
||||||
|
| API Key | your `sk-…` key from Step 3 |
|
||||||
|
|
||||||
|
4. Tap **Check** next to the API Key. It should report a successful connection.
|
||||||
|
5. Tap **Fetch** to load the co-op's models, then select the ones you want to use. If Fetch doesn't work, add a model by hand by typing its name exactly, e.g. `deepseek-flash-green`.
|
||||||
|
6. Save.
|
||||||
|
|
||||||
|
> **Check the API Host.** It ends in `/v1`, with nothing after it. Don't add `/chat/completions`.
|
||||||
|
|
||||||
|
### Chatbox step 6. Turn on images and tools
|
||||||
|
|
||||||
|
Chatbox treats a model as text-only until you tell it otherwise.
|
||||||
|
|
||||||
|
1. Go back to **Settings → Model Provider → Inference Co-op**.
|
||||||
|
2. Open a model's settings.
|
||||||
|
3. Turn on the capabilities it supports, such as **vision** for reading images and **tool use**. The [model table](#which-model-should-i-use) shows which models support what.
|
||||||
|
|
||||||
|
### Chatbox step 7. Say hello
|
||||||
|
|
||||||
|
1. Go back to the main screen and start a **new chat**.
|
||||||
|
2. Tap the model name and choose a model under **Inference Co-op**. Not sure? Start with `deepseek-flash-green`, the web chat's default.
|
||||||
|
3. Type a message and send it.
|
||||||
|
|
||||||
|
If an answer comes back, you're done. Your conversation is saved on this device, in Chatbox.
|
||||||
|
|
||||||
|
**Using more than one device?** Repeat these steps on each one, ideally with its own key. Chats don't move between devices.
|
||||||
|
|
||||||
|
## Which model should I use?
|
||||||
|
|
||||||
|
All co-op models draw from the same $15 monthly allowance. They differ in **privacy**, **energy** and **cost**. If you're adding models by hand, copy these names exactly.
|
||||||
|
|
||||||
|
| If you care most about… | Use this alias | What it is | Vision |
|
||||||
|
| --- | --- | --- | --- |
|
||||||
|
| A good all-rounder, renewable energy | `deepseek-flash-green` | The web chat's default model. Policy-based privacy. | ✓ |
|
||||||
|
| The same model with strong privacy | `deepseek-flash-tee` | Runs inside attested, encrypted hardware (confidential computing). Supports tools. | ✓ |
|
||||||
|
| Fast and inexpensive, renewable energy | `glm-flash-green` | A quick GLM model. Policy-based privacy. | |
|
||||||
|
| The strongest model, with strong privacy | `glm-tee` | GLM flagship in confidential computing. | |
|
||||||
|
|
||||||
|
These are the co-op's **stable aliases**. When a provider retires or replaces a model, the co-op points the alias at its successor, so your app keeps working without changes. The `-green` aliases run on renewable energy; the `-tee` aliases run the same model family in confidential-computing hardware. A blank Vision cell means the co-op doesn't document it. If you want a specific model instead, such as Regolo's zero-retention models, use its full name from the [models page](https://docs.inference.coop/guides/models/).
|
||||||
|
|
||||||
|
> **Which models can use tools (web search and other add-ons)?** Switch on Tools only for models that support it.
|
||||||
|
>
|
||||||
|
> - **Documented by the co-op:** `deepseek-flash-tee` (`tinfoil/deepseek-v4-1-flash`), `regolo/gemma4-31b` and `regolo/mistral-small-4-119b`.
|
||||||
|
> - **Worked in a member's test in Jan:** `greenpt/glm-5.3`, the strongest model in the green tier.
|
||||||
|
> - **Not documented yet:** `deepseek-flash-green`, `glm-flash-green` and `glm-tee`. Try them with Tools on; if you get errors or odd replies, switch Tools off for that model.
|
||||||
|
|
||||||
|
## Keeping an eye on your allowance
|
||||||
|
|
||||||
|
The [Member Dashboard](https://dashboard.inference.coop) shows how much of your $15 is left this month. Neither app shows it. The allowance resets on the day of the month you joined. If you run out, you can buy co-op credit packs, which never expire. You don't need Chatbox's own plans.
|
||||||
|
|
||||||
|
## If something goes wrong
|
||||||
|
|
||||||
|
| What you see | App | What it usually means | Fix |
|
||||||
|
| --- | --- | --- | --- |
|
||||||
|
| Error **401** or **403**, or Check fails | Both | The app isn't sending a valid key | Re-paste the key in the co-op provider's settings. Check there are no spaces at either end. |
|
||||||
|
| Error **404** on every message | Jan | The Base URL is wrong | Make it exactly `https://gateway.inference.coop/v1`. |
|
||||||
|
| Error **404** on every message | Chatbox | The API Host is wrong | API Host `https://gateway.inference.coop/v1` with API Path empty. If that still fails, try API Host `https://gateway.inference.coop` with API Path `/v1/chat/completions`. |
|
||||||
|
| No models listed | Jan | Jan couldn't fetch the list | Click the refresh icon next to Models, or click **+** and type a model name, e.g. `deepseek-flash-green`. |
|
||||||
|
| Fetch finds no models | Chatbox | Chatbox couldn't load the list | Add a model by hand, e.g. `deepseek-flash-green`. |
|
||||||
|
| "Model not found" | Both | A typo in the model name | Copy the name from the model table. |
|
||||||
|
| Messages fail straight away | Both | Wrong API format | Edit the provider and choose OpenAI-compatible. |
|
||||||
|
| The reply keeps repeating "Let me search…" or shows stray `</think>` tags | Both | The model is trying to use a tool it hasn't been given | Stop the reply, then switch on Tools for that model (Jan step 6 or Chatbox step 6) and try again. |
|
||||||
|
| Replies come from a model you didn't expect | Chatbox | You picked a Chatbox AI model | Choose a model listed under **Inference Co-op**. |
|
||||||
|
| A message says your balance is out | Both | You've used this month's $15 | Wait for your reset date, or buy a co-op credit pack. |
|
||||||
|
|
||||||
|
Still stuck? Ask in the co-op's Skillshare room on Matrix, open an issue on the [support tracker](https://git.inference.coop/co-op/support/issues), or email info@inference.coop.
|
||||||
|
|
||||||
|
*Written against Jan 0.8.8's documentation (October 2026), Chatbox's documentation and a third-party Chatbox setup guide (Vercel, September 2026). The Jan steps have been tested by a member; the Chatbox steps haven't yet. Menu names can change between app versions and between phone and desktop.*
|
||||||
+13
-8
@@ -78,18 +78,23 @@ The emoji in the model name marks its **value tier** (the same icons used in the
|
|||||||
a zero-data-retention commitment). The 🌱 emoji marks renewable-powered
|
a zero-data-retention commitment). The 🌱 emoji marks renewable-powered
|
||||||
providers, not a specific company.
|
providers, not a specific company.
|
||||||
|
|
||||||
| Model | Provider | Privacy | Green | Vision | Context | Pricing (in / out / cached) | Notes |
|
| Model | Provider | Privacy | Green | Vision | Context | Pricing (EUR per 1M, in / out / cached) | Notes |
|
||||||
|---|---|---|---|---|---|---|---|
|
|---|---|---|---|---|---|---|---|
|
||||||
| `🌱 greenpt/deepseek-v4.1-flash` | GreenPT | policy | ✅ 100% renewable | ✅ | 1M | $0.36 / $1.45 / $0.04 | **Default.** DeepSeek's multimodal reasoning model, renewable energy; TEE twin below. Serves the **1017 snapshot** (17 Oct 2026) as of 2026-11-16; GreenPT no longer recommends the base release. The id keeps its version-free name so existing configs keep working. |
|
| `🌱 greenpt/deepseek-v4.1-flash` | GreenPT | policy | ✅ 100% renewable | ✅ | 1M | €0.36 / €1.45 / €0.04 | **Default.** DeepSeek's multimodal reasoning model, renewable energy; TEE twin below. Serves the **1017 snapshot** (17 Oct 2026) as of 2026-11-16; GreenPT no longer recommends the base release. The id keeps its version-free name so existing configs keep working. |
|
||||||
| `🔒 tinfoil/deepseek-v4-1-flash` | Tinfoil | architectural | undisclosed | ✅ | 1M | $0.65 / $1.45 / $0.13 | TEE-protected version of the default; image input, tool calling, long docs/agents. |
|
| `🔒 tinfoil/deepseek-v4-1-flash` | Tinfoil | architectural | undisclosed | ✅ | 1M | $0.65 / $1.45 / $0.13 | TEE-protected version of the default; image input, tool calling, long docs/agents. |
|
||||||
| `🔒 tinfoil/glm-5.3` | Tinfoil | architectural | undisclosed | — | 1M | $1.80 / $5.75 / $0.45 | GLM flagship, TEE-protected; strongest private-tier model for agentic coding and long-horizon tasks. |
|
| `🔒 tinfoil/glm-5.3` | Tinfoil | architectural | undisclosed | — | 1M | $1.80 / $5.75 / $0.45 | GLM flagship, TEE-protected; strongest private-tier model for agentic coding and long-horizon tasks. |
|
||||||
| `🔒 tinfoil/gpt-oss-120b` | Tinfoil | architectural | undisclosed | — | 131K | $0.15 / $0.60 / — | Lightweight open-weight reasoning; cheapest private tier. |
|
| `🔒 tinfoil/gpt-oss-120b` | Tinfoil | architectural | undisclosed | — | 131K | $0.15 / $0.60 / — | Lightweight open-weight reasoning; cheapest private tier. |
|
||||||
| `🌱 greenpt/glm-5.3-flash` | GreenPT | policy | ✅ 100% renewable | — | 1M | $0.11 / $0.44 / $0.022 | Fast GLM model, renewable energy. |
|
| `🌱 greenpt/glm-5.3-flash` | GreenPT | policy | ✅ 100% renewable | — | 1M | €0.11 / €0.44 / €0.022 | Fast GLM model, renewable energy. |
|
||||||
| `🌱 greenpt/glm-5.3` | GreenPT | policy | ✅ 100% renewable | — | 1M | $1.10 / $4.40 / $0.275 | GLM flagship — strongest agentic model in the green tier. |
|
| `🌱 greenpt/glm-5.3` | GreenPT | policy | ✅ 100% renewable | — | 1M | €1.10 / €4.40 / €0.275 | GLM flagship — strongest agentic model in the green tier. |
|
||||||
| `🌱 regolo/apertus-70b` | Regolo | policy + ZDR | ✅ 100% renewable | ✅ | 262K | $1.16 / $3.94 / — | Fully open sovereign model (Apache-2.0), large/capable, image understanding. |
|
| `🌱 regolo/apertus-70b` | Regolo | policy + ZDR | ✅ 100% renewable | ✅ | 262K | €1.00 / €3.40 / — | Fully open sovereign model (Apache-2.0), large/capable, image understanding. |
|
||||||
| `🌱 regolo/qwen3.5-122b` | Regolo | policy + ZDR | ✅ 100% renewable | ✅ | 262K | $0.70 / $3.94 / — | Large vision+reasoning MoE (Qwen 3.5, 122B-A10B); 262K context. |
|
| `🌱 regolo/qwen3.5-122b` | Regolo | policy + ZDR | ✅ 100% renewable | ✅ | 262K | €0.60 / €3.40 / — | Large vision+reasoning MoE (Qwen 3.5, 122B-A10B); 262K context. |
|
||||||
| `🌱 regolo/gemma4-31b` | Regolo | policy + ZDR | ✅ 100% renewable | ✅ | 262K | $0.40 / $0.60 / — | Google's dense multimodal Gemma 4 (31B); image input, native function calling. Served from Regolo's EU renewable-powered infrastructure. |
|
| `🌱 regolo/gemma4-31b` | Regolo | policy + ZDR | ✅ 100% renewable | ✅ | 262K | €0.40 / €0.60 / — | Google's dense multimodal Gemma 4 (31B); image input, native function calling. Served from Regolo's EU renewable-powered infrastructure. |
|
||||||
| `🌱 regolo/mistral-small-4-119b` | Regolo | policy + ZDR | ✅ 100% renewable | ✅ | 262K | $0.20 / $0.70 / — | Mistral's hybrid Small 4 (119B) — instruct + reasoning + coding unified; image input, tool calling. Served from Regolo's EU renewable-powered infrastructure. |
|
| `🌱 regolo/mistral-small-4-119b` | Regolo | policy + ZDR | ✅ 100% renewable | ✅ | 262K | €0.20 / €0.70 / — | Mistral's hybrid Small 4 (119B) — instruct + reasoning + coding unified; image input, tool calling. Served from Regolo's EU renewable-powered infrastructure. |
|
||||||
|
|
||||||
|
**Currency.** GreenPT and Regolo publish prices in **EUR**; those are the stable
|
||||||
|
list prices above. The gateway bills in USD, converting at the **ECB daily
|
||||||
|
reference rate**, so a member's dollar cost follows the exchange rate rather than
|
||||||
|
a frozen conversion. Tinfoil publishes in USD and is listed as such.
|
||||||
|
|
||||||
Vision is verified working through the co-op gateway (base64 image input via
|
Vision is verified working through the co-op gateway (base64 image input via
|
||||||
`/v1/chat/completions`, standard OpenAI format). In the chat UI, just attach
|
`/v1/chat/completions`, standard OpenAI format). In the chat UI, just attach
|
||||||
|
|||||||
+3
-1
@@ -3,7 +3,9 @@
|
|||||||
A central part of our mission is to use collective purchasing power to generate better options for AI service than we have on our own. We have no investors or outside donors. Our co-op depends on its members.
|
A central part of our mission is to use collective purchasing power to generate better options for AI service than we have on our own. We have no investors or outside donors. Our co-op depends on its members.
|
||||||
|
|
||||||
Usage credits are priced at what the co-op pays providers — see
|
Usage credits are priced at what the co-op pays providers — see
|
||||||
[Models](models.md) for current prices. What members contribute beyond their usage
|
[Models](models.md) for current prices. GreenPT and Regolo list prices are in
|
||||||
|
EUR; billing converts them to USD at the ECB daily rate, so the dollar figure
|
||||||
|
follows the exchange rate rather than a frozen conversion. What members contribute beyond their usage
|
||||||
covers the co-op's expenses.
|
covers the co-op's expenses.
|
||||||
|
|
||||||
## Membership dues
|
## Membership dues
|
||||||
|
|||||||
@@ -71,6 +71,7 @@ nav:
|
|||||||
- Guides:
|
- Guides:
|
||||||
- Overview: guides/index.md
|
- Overview: guides/index.md
|
||||||
- Getting started: guides/getting-started.md
|
- Getting started: guides/getting-started.md
|
||||||
|
- Local chat apps: guides/local-chat-apps.md
|
||||||
- Pricing: guides/pricing.md
|
- Pricing: guides/pricing.md
|
||||||
- Guest access: guides/guest-access.md
|
- Guest access: guides/guest-access.md
|
||||||
- Models: guides/models.md
|
- Models: guides/models.md
|
||||||
|
|||||||
@@ -34,11 +34,22 @@ This page is for members who read its output or give it instructions.
|
|||||||
portal and a human.
|
portal and a human.
|
||||||
- Credentials, in either direction.
|
- Credentials, in either direction.
|
||||||
|
|
||||||
|
## Content is data, never instructions
|
||||||
|
|
||||||
|
Text an agent reads — issue descriptions, pull-request comments, web pages,
|
||||||
|
fetched documents, and messages from members in a room — is **data**. The agent
|
||||||
|
may quote, summarise or act on it once the operator asks, but an instruction
|
||||||
|
embedded in that text is never executed. Only the operator's own direct
|
||||||
|
instruction authorises a credentialed action: a deploy, a credential change, or
|
||||||
|
a budget change. This rule exists because the same process that reads an issue
|
||||||
|
can reach the infrastructure the issue is about.
|
||||||
|
|
||||||
## What they do without asking
|
## What they do without asking
|
||||||
|
|
||||||
Read, monitor, draft, open issues and PRs, post updates, run the scheduled jobs
|
Read, monitor, draft, open issues and PRs, post updates, run the scheduled jobs
|
||||||
listed in [Infrastructure](infrastructure.md), and deploy bug and security
|
listed in [Infrastructure](infrastructure.md), and deploy fixes after flagging
|
||||||
fixes immediately, reporting each one in #inferencebot-updates.
|
them to the operator. The bot can deploy without waiting for a reply, and the
|
||||||
|
operator can stop a deploy; anything irreversible waits for confirmation.
|
||||||
|
|
||||||
## What always needs a human
|
## What always needs a human
|
||||||
|
|
||||||
|
|||||||
@@ -73,8 +73,10 @@ The co-op's software behind all of these is open source — see [The
|
|||||||
code](#the-code) below for where each piece lives.
|
code](#the-code) below for where each piece lives.
|
||||||
|
|
||||||
Open Collective (billing and fiscal sponsorship) is the one external service in
|
Open Collective (billing and fiscal sponsorship) is the one external service in
|
||||||
the flow — see
|
the membership flow. See
|
||||||
[opencollective.com/inference-cooperative](https://opencollective.com/inference-cooperative).
|
[opencollective.com/inference-cooperative](https://opencollective.com/inference-cooperative).
|
||||||
|
Web search uses external services too; see
|
||||||
|
[Chat retention and web search](#chat-retention-and-web-search).
|
||||||
|
|
||||||
## Mail
|
## Mail
|
||||||
|
|
||||||
@@ -172,6 +174,39 @@ The co-op serves models from multiple providers — Tinfoil for architectural
|
|||||||
privacy, GreenPT and Regolo for renewable energy. See the [model list](../guides/models.md),
|
privacy, GreenPT and Regolo for renewable energy. See the [model list](../guides/models.md),
|
||||||
the single source of truth for which models are available and how they're named.
|
the single source of truth for which models are available and how they're named.
|
||||||
|
|
||||||
|
## Chat retention and web search
|
||||||
|
|
||||||
|
**Saved chats** live in the chat database and its search index until the member
|
||||||
|
deletes them. Web-search tool calls are part of that record: the query and the
|
||||||
|
results returned are stored with the message.
|
||||||
|
|
||||||
|
**Temporary chats** are server-backed — messages must reach the server while the
|
||||||
|
chat is running — so they are not client-only. The chat is configured to delete
|
||||||
|
them from the database about **one hour after creation** (`interface.temporaryChatRetention: 1`
|
||||||
|
in the chat configuration; one hour is the minimum this LibreChat version
|
||||||
|
accepts). They are hidden from history immediately, and the database enforces the
|
||||||
|
expiry automatically. Temporary chats created before this setting took effect
|
||||||
|
keep their original 30-day expiry until they age out.
|
||||||
|
|
||||||
|
**Backups are a separate layer.** Cloudron backups are whole-app snapshots and
|
||||||
|
cannot exclude individual chats, so a temporary chat present when a backup runs
|
||||||
|
can remain recoverable from that backup until the backup itself expires (see
|
||||||
|
[Backups](#backups)).
|
||||||
|
|
||||||
|
**Web search** in the chat uses **DuckDuckGo and Brave** through the co-op's
|
||||||
|
self-hosted SearXNG instance. Queries are sent from the co-op server, so the
|
||||||
|
upstream engines see the query but not the member's IP or identity. The SearXNG
|
||||||
|
instance is also publicly reachable at search.inference.coop, and its logs can
|
||||||
|
contain query text when an upstream engine request fails; those log lines carry
|
||||||
|
no member identity or IP, and are retained only briefly. The reverse proxy does
|
||||||
|
not log search queries.
|
||||||
|
|
||||||
|
LibreChat reads the pages behind the results through the co-op's **own
|
||||||
|
page-fetch service** (`fetch.inference.coop`), a small app on our Cloudron. It
|
||||||
|
runs with no access log and keeps no copy of URLs or page text; it refuses
|
||||||
|
private, loopback, and internal addresses. The
|
||||||
|
[privacy policy](../governance/privacy-policy.md#5-search) describes it.
|
||||||
|
|
||||||
## Security posture (plain language)
|
## Security posture (plain language)
|
||||||
|
|
||||||
- **Member isolation.** Each API key is scoped to its owner's team and budget; a
|
- **Member isolation.** Each API key is scoped to its owner's team and budget; a
|
||||||
|
|||||||
+42
-69
@@ -17,11 +17,11 @@ repository root.
|
|||||||
| `logo.svg` | Co-op logo (shared with the website repo) |
|
| `logo.svg` | Co-op logo (shared with the website repo) |
|
||||||
| `build.sh` | Stage the Markdown into `.site-src/`, render to `.site-build/` |
|
| `build.sh` | Stage the Markdown into `.site-src/`, render to `.site-build/` |
|
||||||
| `hooks.py` | MkDocs hooks: directory-link rewriting + content-hashed stylesheet URLs |
|
| `hooks.py` | MkDocs hooks: directory-link rewriting + content-hashed stylesheet URLs |
|
||||||
| `deploy.sh` | Push the build into the Surfer app container |
|
| `deploy.sh` | Manual publish of the build into the Surfer app (needs a Cloudron token) |
|
||||||
| `poll-watcher.sh` | Polls Gitea main every 60s; deploys on change (agent host) |
|
| `poll-watcher.sh` | Legacy poller; no longer installed — superseded by the host-owned poller |
|
||||||
| `docs-deploy-poll.service` | systemd unit for the poller |
|
| `docs-deploy-poll.service` | systemd unit for the poller (runs the host-owned script) |
|
||||||
| `webhook-receiver.py` | Gitea webhook → pull → build → deploy (agent host) |
|
| `webhook-receiver.py` | Webhook receiver; not installed (see below) |
|
||||||
| `webhook-receiver.service` | systemd unit for the receiver |
|
| `webhook-receiver.service` | systemd unit for the receiver; not installed |
|
||||||
| `requirements.txt` | Pinned Python build toolchain |
|
| `requirements.txt` | Pinned Python build toolchain |
|
||||||
|
|
||||||
Nothing external is loaded by the site: no CDN, no third-party font service.
|
Nothing external is loaded by the site: no CDN, no third-party font service.
|
||||||
@@ -71,79 +71,52 @@ Override the destination with `SURFER_APP` (the app's Cloudron location) and
|
|||||||
|
|
||||||
## Automatic rebuilds (push to main)
|
## Automatic rebuilds (push to main)
|
||||||
|
|
||||||
Two mechanisms keep the site in step with `main`; both run on the agent host
|
`docs-deploy-poll.service` polls Gitea every 60 seconds and deploys whenever
|
||||||
and deploy into the docs Cloudron app above.
|
`main` moves, so a push appears on the site within about a minute with no human
|
||||||
|
action. Edit, commit, push — that is the whole deployment story.
|
||||||
|
|
||||||
**Polling (running now).** `docs-deploy-poll.service` polls Gitea every 60
|
**The credential-bearing steps are host-owned, not repository code.** The
|
||||||
seconds and deploys whenever `main` moves. A push appears on the site within
|
poller runs a root-owned script (`/usr/local/sbin/docs-poll`) that does two
|
||||||
about a minute, with no human action. The Gitea webhook alone was not enough
|
separate jobs:
|
||||||
because the agent host's cloud firewall only admits inbound SSH — a webhook
|
|
||||||
POST is silently dropped — while outbound access to Gitea works.
|
|
||||||
|
|
||||||
The service builds from a **dedicated clean clone** at
|
1. **Build as `docsbuild`.** The repository's build logic (`build.sh` → MkDocs
|
||||||
`/home/ubuntu/.docs-publisher`, not from anyone's working copy, so uncommitted
|
→ `hooks.py`) runs as an unprivileged system user with a scrubbed
|
||||||
edits in a working clone can never block a deploy. Edit, commit, push — that
|
environment, from its own clean clone at `/var/lib/docs-publisher/repo`
|
||||||
is the whole deployment story.
|
with its own venv. That user cannot read `/home/ubuntu` (mode 750), so repo
|
||||||
|
code cannot see any co-op credential — the Cloudron token, the gateway
|
||||||
|
master key, the agent's env file.
|
||||||
|
2. **Publish with a root-owned script.** `/usr/local/sbin/docs-publish` runs
|
||||||
|
no repository code. It takes only the built directory, writes `meta.json`,
|
||||||
|
and pushes it into the Surfer app using `CLOUDRON_TOKEN` from
|
||||||
|
`/etc/docs-deploy.env` (root-only, mode 0600).
|
||||||
|
|
||||||
**Webhook (wired, waiting on one port).** A Gitea webhook is registered on
|
A commit that lands on `main` therefore cannot execute anything with the
|
||||||
`co-op/docs` (push events, branch `main`) pointing at the receiver below. The
|
Cloudron token. It can only influence the bytes of the site.
|
||||||
moment the Infomaniak panel allows inbound TCP to the agent host — port 8787
|
|
||||||
from the Cloudron box 179.237.86.116 is enough — start the receiver and pushes
|
|
||||||
deploy instantly instead of within a minute:
|
|
||||||
|
|
||||||
```sh
|
**The webhook receiver is installed but not running.** `docs-deploy-webhook`
|
||||||
sudo systemctl enable --now docs-deploy-webhook
|
is inactive and nothing listens on 8787. It predates this split, loads the
|
||||||
tail -f /home/ubuntu/docs-deploy.log # what both mechanisms are doing
|
agent's env file, and runs repo scripts with the Cloudron token; do not enable
|
||||||
```
|
it without porting it to the same host-owned build/publish split. The Gitea
|
||||||
|
webhook registration is harmless while the receiver is down.
|
||||||
The receiver authenticates webhooks with an HMAC-SHA256 shared secret
|
|
||||||
(`DEPLOY_WEBHOOK_SECRET` in the agent host's env file) and only accepts pushes
|
|
||||||
to `main` of `co-op/docs` from the Cloudron box. Woodpecker CI (Cloudron
|
|
||||||
catalog) could do the same job inside Cloudron, at the cost of running another
|
|
||||||
app; the agent-host mechanisms were chosen because they add no new Cloudron app.
|
|
||||||
|
|
||||||
Each deploy writes `meta.json` into the site with the commit it was built
|
Each deploy writes `meta.json` into the site with the commit it was built
|
||||||
from, so a deploy can be verified from the served site itself:
|
from, so a deploy can be verified from the served site itself:
|
||||||
https://docs.inference.coop/meta.json
|
https://docs.inference.coop/meta.json
|
||||||
|
|
||||||
## One build environment (2026-11-12)
|
If a deploy breaks, roll back with the saved unit
|
||||||
|
(`/root/docs-deploy-poll.service.before-split`) and the previous build in
|
||||||
|
`/var/lib/docs-publisher/repo/.site-build`; the poller retries every 60 seconds
|
||||||
|
and sends one Matrix alert after 3 consecutive failures.
|
||||||
|
|
||||||
The deploy used to have TWO build environments — this repo's `.venv-docs` and
|
## Build environment
|
||||||
a second private venv in the poller's checkout at
|
|
||||||
`/home/ubuntu/.docs-publisher/.venv-docs`. They diverged twice, each time
|
|
||||||
silently delaying a deploy (the brand.css cache-busting confusion, then a
|
|
||||||
missing `mkdocs-redirects` that failed every build for ~15 minutes while the
|
|
||||||
poller retried without telling anyone). Consolidated:
|
|
||||||
|
|
||||||
- **ONE venv.** Every trigger — the poller, the (dormant) webhook receiver, a
|
`publishing/requirements.txt` pins every package the build needs (`mkdocs`,
|
||||||
manual `publishing/build.sh`, CI — builds with the canonical checkout's
|
`mkdocs-material`, `mkdocs-redirects`). `build.sh` verifies the build venv
|
||||||
venv: `~/repos/docs/.venv-docs`. The poller's private venv was deleted.
|
against it before every build and installs anything missing or off-version
|
||||||
- **The dedicated checkout stays, by design.** The poller still builds from
|
(fast local no-op when current); it also fails loudly if `mkdocs.yml`
|
||||||
`/home/ubuntu/.docs-publisher`, its own clean clone: uncommitted edits in a
|
configures a plugin that `requirements.txt` does not pin.
|
||||||
working clone must never block a deploy or leak into the published site.
|
|
||||||
- **Drift check.** Before every build the poller compares `publishing/` and
|
|
||||||
`mkdocs.yml` between its checkout and the canonical one; any mismatch fails
|
|
||||||
the deploy loudly (with a diff and the fix — `git -C ~/repos/docs pull
|
|
||||||
--ff-only`), and the failure counts toward the alert below. A canonical
|
|
||||||
checkout that lags behind main trips this too, on purpose: a deploy of
|
|
||||||
logic the canonical source cannot reproduce is the failure mode this exists
|
|
||||||
to prevent. A missing canonical checkout is fatal as well.
|
|
||||||
- **Plugin gate + self-heal.** `publishing/requirements.txt` pins every
|
|
||||||
package the build needs (`mkdocs`, `mkdocs-material`, `mkdocs-redirects`).
|
|
||||||
`build.sh` verifies the venv against it before every build and installs
|
|
||||||
anything missing or off-version (fast local no-op when current); it also
|
|
||||||
fails loudly if `mkdocs.yml` configures a plugin that `requirements.txt`
|
|
||||||
does not pin. The poller runs this as its pre-deploy check via
|
|
||||||
`build.sh --check-only`.
|
|
||||||
- **Failure alerting.** After 3 consecutive deploy failures the poller writes
|
|
||||||
a marker (`~/.docs-deploy.alert`) and sends ONE message to the InferenceBot
|
|
||||||
HQ Matrix room naming the failing commit — never more than one message per
|
|
||||||
hour (`~/.docs-deploy.last-alert`). The counter (`~/.docs-deploy.failcount`)
|
|
||||||
resets on the next successful deploy. A deploy that succeeds silently
|
|
||||||
resets everything; nothing announces routine successes.
|
|
||||||
|
|
||||||
Files: `~/.docs-deploy.state` (last deployed commit), `~/.docs-deploy.lock`
|
The deployed poller keeps one build venv at
|
||||||
(deploy lock), `~/.docs-deploy.failcount`, `~/.docs-deploy.alert`,
|
`/var/lib/docs-publisher/repo/.venv-docs`, owned by `docsbuild`. A manual
|
||||||
`~/.docs-deploy.last-alert`. Manual deploys should respect the lock:
|
`publishing/build.sh` uses `.venv-docs` in whatever checkout you run it from;
|
||||||
`flock -n ~/.docs-deploy.lock bash publishing/build.sh && flock -n
|
that is fine for local previews and does not affect deploys.
|
||||||
~/.docs-deploy.lock bash publishing/deploy.sh`.
|
|
||||||
@@ -1,41 +1,42 @@
|
|||||||
# systemd unit for the docs auto-deploy poller (agent host).
|
# systemd unit for the docs auto-deploy poller (agent host).
|
||||||
#
|
#
|
||||||
# docs-deploy-poll.service ALWAYS ON. Polls Gitea every 60s; deploys on
|
# docs-deploy-poll.service ALWAYS ON. Polls Gitea every 60s; deploys on
|
||||||
# any change to main. Works with the agent
|
# any change to main.
|
||||||
# host's current firewall (outbound only).
|
|
||||||
#
|
#
|
||||||
# docs-deploy-webhook.service INSTALLED, INACTIVE UNTIL THE PORT IS OPEN.
|
# docs-deploy-webhook.service INSTALLED, INACTIVE. It predates the
|
||||||
# Instant push -> deploy once the Infomaniak
|
# build/publish split, loads the agent's env
|
||||||
# panel allows inbound TCP to the agent host
|
# file, and runs repo scripts with the Cloudron
|
||||||
# (the Gitea webhook is already registered).
|
# token. Do not enable it until it is ported to
|
||||||
|
# the same split.
|
||||||
#
|
#
|
||||||
# Install:
|
# Install:
|
||||||
# sudo cp publishing/docs-deploy-poll.service /etc/systemd/system/
|
# sudo install -o root -g root -m 0644 publishing/docs-deploy-poll.service \
|
||||||
|
# /etc/systemd/system/docs-deploy-poll.service
|
||||||
# sudo systemctl daemon-reload
|
# sudo systemctl daemon-reload
|
||||||
# sudo systemctl enable --now docs-deploy-poll
|
# sudo systemctl enable --now docs-deploy-poll
|
||||||
#
|
#
|
||||||
# poll-watcher.sh itself needs NO manual copy: the service runs the copy in
|
# The unit runs a HOST-OWNED script, /usr/local/sbin/docs-poll, which is not
|
||||||
# the dedicated checkout (/home/ubuntu/.docs-publisher), which git pull keeps
|
# copied from this repository. That script:
|
||||||
# at main on every deploy, and the watcher re-execs itself when a deploy
|
# * builds as the unprivileged `docsbuild` user from its own checkout at
|
||||||
# changed it.
|
# /var/lib/docs-publisher/repo (a scrubbed environment, no read access to
|
||||||
|
# /home/ubuntu, so repo code cannot see any co-op credential);
|
||||||
|
# * publishes with /usr/local/sbin/docs-publish, a root-owned script that
|
||||||
|
# runs no repository code and reads the Cloudron token from
|
||||||
|
# /etc/docs-deploy.env (root-only, mode 0600).
|
||||||
#
|
#
|
||||||
# ONE BUILD ENVIRONMENT: the poller builds from its own dedicated checkout
|
# Repo code (build.sh, hooks.py) therefore never executes with a credential.
|
||||||
# (uncommitted edits in a working clone must never block or leak into a
|
# See publishing/README.md.
|
||||||
# deploy) but with the ONE canonical venv, DOCS_CANONICAL_DIR/.venv-docs, and
|
|
||||||
# drift-checks its publishing/ tree against the canonical checkout before
|
|
||||||
# every build. See publishing/README.md.
|
|
||||||
|
|
||||||
[Unit]
|
[Unit]
|
||||||
Description=Inference docs: poll Gitea main and deploy to Surfer
|
Description=Inference docs: poll Gitea main, build unprivileged, publish without repo code
|
||||||
After=network-online.target
|
After=network-online.target
|
||||||
Wants=network-online.target
|
Wants=network-online.target
|
||||||
|
|
||||||
[Service]
|
[Service]
|
||||||
User=ubuntu
|
User=root
|
||||||
WorkingDirectory=/home/ubuntu/.docs-publisher
|
Environment=DOCS_REPO_DIR=/var/lib/docs-publisher/repo
|
||||||
Environment=DOCS_REPO_DIR=/home/ubuntu/.docs-publisher
|
Environment=DOCS_DEPLOY_LOG=/var/log/docs-deploy.log
|
||||||
Environment=DOCS_CANONICAL_DIR=/home/ubuntu/repos/docs
|
ExecStart=/usr/local/sbin/docs-poll
|
||||||
ExecStart=/bin/bash /home/ubuntu/.docs-publisher/publishing/poll-watcher.sh
|
|
||||||
Restart=on-failure
|
Restart=on-failure
|
||||||
RestartSec=10
|
RestartSec=10
|
||||||
|
|
||||||
|
|||||||
Reference in new issue
Block a user