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).
2.9 KiB
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.
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:
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.
cd OutlineKit
swift build
swift test
3. Open the app in Xcode
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:
./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— project conventions, phased build order, what's in/out of scope right now.docs/ARCHITECTURE.md— deeper technical rationale (API surface, the realtime collaboration transport, the CRDT engine, known risk areas).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.