Puranjay Savar Mattas
8c35710521
CODEOWNERS, CONTRIBUTING.md, SECURITY.md, SETUP.md, and the .gitea issue/PR templates, rewritten for Outpost (they started as copies from an unrelated project's templates - stripped the cross-repo/ticket-ID conventions and the entirely different tech stack in SETUP.md, replaced with this repo's actual submodule/OutlineKit/Xcode workflow).
92 lines
2.9 KiB
Markdown
92 lines
2.9 KiB
Markdown
# Outpost Setup Guide
|
|
|
|
## Prerequisites
|
|
|
|
- macOS with a recent Xcode (Xcode 16 or later)
|
|
- A self-hosted Outline instance (or getoutline.com) and a personal API
|
|
key — Settings → API Keys on that instance. Outpost only ever talks
|
|
to Outline's public REST/WebSocket API; it doesn't vendor or run any
|
|
part of Outline's server.
|
|
|
|
## 1. Clone with submodules
|
|
|
|
The vendored OpenAPI reference (`docs/reference/outline-openapi`) is a
|
|
git submodule.
|
|
|
|
```bash
|
|
git clone --recurse-submodules <repo-url>
|
|
# or, if you already cloned without it:
|
|
git submodule update --init --recursive
|
|
```
|
|
|
|
To pull that submodule up to whatever's newest upstream:
|
|
|
|
```bash
|
|
git submodule update --remote docs/reference/outline-openapi
|
|
```
|
|
|
|
## 2. Build and test `OutlineKit`
|
|
|
|
`OutlineKit` is a standalone Swift package (the REST client layer) and
|
|
the only part of this repo with a reliable command-line build/test path.
|
|
|
|
```bash
|
|
cd OutlineKit
|
|
swift build
|
|
swift test
|
|
```
|
|
|
|
## 3. Open the app in Xcode
|
|
|
|
```bash
|
|
open Outpost.xcodeproj
|
|
```
|
|
|
|
- Select the **Outpost** scheme.
|
|
- In **Signing & Capabilities**, pick your own team. A free personal
|
|
Apple ID team works fine for building and running locally — it just
|
|
means the app isn't notarized, so distributed builds trigger
|
|
Gatekeeper's "unidentified developer" warning on other machines (see
|
|
`scripts/package-dmg.sh`, which ships a README explaining the bypass).
|
|
- Run. There's no way to build the app target reliably from the CLI in
|
|
this project's current setup — use Xcode.
|
|
|
|
## 4. Sign in
|
|
|
|
On first launch, enter your Outline instance's URL and the API key
|
|
from step 0. The token is stored in the system Keychain only.
|
|
|
|
## 5. Packaging a release build
|
|
|
|
After archiving in Xcode (Product → Archive → Distribute App → Copy
|
|
App), package it into a DMG:
|
|
|
|
```bash
|
|
./scripts/package-dmg.sh /path/to/exported/Outpost.app
|
|
```
|
|
|
|
This also prints a Markdown changelog (grouped by commit type, since
|
|
the last git tag) for pasting into release notes.
|
|
|
|
## Where to go next
|
|
|
|
- [`CLAUDE.md`](CLAUDE.md) — project conventions, phased build order, what's in/out of scope right now.
|
|
- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — deeper technical rationale (API surface, the realtime collaboration transport, the CRDT engine, known risk areas).
|
|
- [`CONTRIBUTING.md`](CONTRIBUTING.md) — branching, commit conventions, PR expectations.
|
|
|
|
## Troubleshooting
|
|
|
|
### `swift build`/`swift test` fails in `OutlineKit`
|
|
Make sure you're running it from inside the `OutlineKit/` directory,
|
|
not the repo root — it's a separate Swift package, not part of the
|
|
Xcode project's own build.
|
|
|
|
### Submodule directory is empty
|
|
You cloned without `--recurse-submodules`. Run
|
|
`git submodule update --init --recursive` from the repo root.
|
|
|
|
### App builds but sign-in fails
|
|
Double-check the server URL (including `https://`) and that the API
|
|
key hasn't been revoked on the Outline instance's Settings → API Keys
|
|
page.
|