Herald/Documentation
← All documentation
Owner setup

Runbook — Real Instagram Connect & Publish (live deployment)

Herald is deployed and live — no local servers, no Tailscale, no .env editing. Everything is done in the browser at:

https://herald.leiritech.com

This runbook takes you from a fresh account to a real Instagram post.

Prerequisites (yours)

  • A Meta app created per owner-meta-app-setup.md, with the Instagram App ID + Secret.
  • Your Instagram account is Business/Creator and accepted the Instagram Tester invite (the app stays in Development Mode — no App Review needed to post to your own account).

1. Create your workspace

Open https://herald.leiritech.com → Create a workspace → sign up. You land on the dashboard.

2. Configure the Meta credentials (in the UI, encrypted)

Settings → Platform apps → Instagram → paste the Instagram App ID (Client ID) and Instagram App Secret → Save. The card flips to "Configured ✓". The secret is encrypted at rest and never shown again.

3. Register Herald's redirect URI in the Meta app

In the Meta app's Instagram-login Valid OAuth Redirect URIs, add this exact URL:

https://herald.leiritech.com/api/oauth/instagram/callback

(Exact string match, HTTPS. If Herald later moves to your own domain, update this.)

4. Connect your Instagram account

Accounts → Connect Instagram → Instagram shows its consent screen (Herald's app name + content-publish permission) → Allow. You're redirected back and the account shows Connected with your handle. A Personal account is rejected with a clear message — switch it to Business/Creator and retry.

5. (Required for image posts) Set up media hosting — Cloudflare R2

Instagram's API fetches an image by public URL, so Herald must host media publicly. Until R2 is configured, an image upload returns "Media storage is not configured" (503). Create a Cloudflare R2 bucket + API token with public read, then set on the Railway web and worker services: R2_ACCOUNT_ID, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY, MEDIA_BUCKET, MEDIA_PUBLIC_BASE_URL (the bucket's public base URL). Redeploy.

6. Publish

Compose → write a caption → add an image → tick your Instagram account → Publish now. Herald uploads the image (R2), runs Instagram's 2-step publish, and shows a per-target result with a View post ↗ permalink. Open it — that's the real post.

Verify it worked

  • Accounts shows the connected account as active.
  • Posts shows the post as published, and /posts/{id} shows the live permalink.
  • A failed target shows a clear error and a Retry failed button.

Notes

  • Scheduling: Compose → Schedule publishes at the due time via the worker process.
  • LinkedIn: the connector is built, but a real LinkedIn post waits on LinkedIn approving your Community Management API access (see owner-linkedin-app-setup.md).
  • Multi-tenant production (posting for other people's accounts, not just your tester) needs Meta App Review + Business Verification — start that early; not needed to test now.