Playbooks — Every Task, Step by Step

The lifecycle of one post — and where you step in

Before the playbooks, here is the whole journey of a single post. Five stages run automatically on a schedule; the two green markers are where a human can step in.

Playbook 1 — Connect a social account

Every network is added the same way in spirit: authorize the account once, and the hub can post to it forever. Two kinds of networks: app-password ones (easiest) and developer-app ones (a one-time setup, sometimes an approval wait). Do the easy ones first.

Bluesky (easiest — 3 minutes, free)

Do it — step by step

1. In a browser, sign in to bsky.app with the account you want to post from.
2. Go to Settings → Privacy and security → App passwords, click Add app password, name it “WholeReach”, and copy the password it shows (you only see it once).
3. Open the hub at postiz.wholetech.com and sign in.
4. Click Add channel → Bluesky. Enter service https://bsky.social, your handle (e.g. walhus.bsky.social), and paste the app password. Click connect.
5. Done — a test post confirms it. The channel now shows in the hub.

Under the hood (for the technical reader)

The hub stores the returned access token in the Integration table; the publisher reads it directly. Nothing to install.

Mastodon (easy — free)

Do it — step by step

1. Sign in to the hub at postiz.wholetech.com.
2. Click Add channel → Mastodon. Enter your instance URL (e.g. https://mastodon.social).
3. You're bounced to Mastodon to log in and click Authorize. You return to the hub and the channel is connected.

X / Twitter (developer app — paid per post)

Do it — step by step

1. Go to console.x.com, sign in with the account you'll post from, and create a project + app. Set the app to Read and Write and type “Web App / Automated App or Bot”.
2. In the app's User authentication settings, set the callback URL to https://postiz.wholetech.com/integrations/social/x.
3. Copy the app's API Key and API Secret.
4. Install the keys on the hub — run this in your own terminal and paste the keys when prompted (they never pass through anyone else):

   ssh -t root@64.227.29.192 /opt/postiz/set-x-keys.sh

5. Back in the hub UI, click Add channel → X and authorize.
6. Load credit: in the X developer portal, add funds (a $25 credit lasts months at our cap). See Playbook 11 for the spend cap.

Under the hood (for the technical reader)

Auth is OAuth 1.0a; keys live in /opt/postiz/social.env (root-only). The publisher signs each request with the stored token.

LinkedIn (developer app + review — free)

Do it — step by step

1. Go to developer.linkedin.com, create an app, and link it to a LinkedIn Page you control.
2. Request the Community Management API (page posting). This triggers LinkedIn's review.
3. Set the callback to https://postiz.wholetech.com/integrations/social/linkedin.
4. When approved, copy the Client ID + Secret and install them:

   ssh -t root@64.227.29.192 /opt/postiz/set-linkedin-keys.sh

5. In the hub, Add channel → LinkedIn and authorize.

Facebook + Instagram (Meta app + business review — free)

Do it — step by step

1. Go to developers.facebook.com, create an app (type “Business”), and add the Instagram Graph API and Pages products.
2. Complete Business Verification and request the permissions to post to a Page and its linked Instagram professional account. Provide the privacy policy (automarketingengine.com/privacy/) and the data-deletion URL (the #data-deletion section on that page).
3. Set the callback to https://postiz.wholetech.com/integrations/social/facebook.
4. After approval, copy the App ID + Secret and install them:

   ssh -t root@64.227.29.192 /opt/postiz/set-meta-keys.sh

5. In the hub, Add channel → Facebook, authorize, and pick the Page (and its linked Instagram account).

Under the hood (for the technical reader)

Playbook 2 — Approve, edit, or skip a post

Approve, edit, or skip

Do it — step by step

1. Open the approval link for the account (how to create one: Managing Clients). No password — the link itself is the key.
2. You see a stack of cards, one per drafted post: the text, the network(s), and the scheduled time.
3. For each card, tap Approve (it will publish at its time), Edit (change the wording, then approve), or Skip (it won't publish; you can note why).
4. Held cards (missing a verified fact) are shown but can't be approved until the fact is supplied.
5. That's it — approved posts publish automatically at their scheduled time.

Under the hood (for the technical reader)

The queue is served by portal_api.py (POST /portal-api/act with approve|edit|skip). Operators can also flip a post directly:

ssh root@64.227.29.192 "python3 -c \"import sqlite3;c=sqlite3.connect('/opt/portal/portal.db');c.execute('UPDATE posts SET state=1 WHERE id=123'.replace('1',chr(39)+'approved'+chr(39)));c.commit()\""

Playbook 3 — Post something right now

Publish immediately

Do it — step by step

1. Find the post you want (see Playbook 9 to list the queue and get its ID).
2. Set its time to now and make sure it's approved, then run the publisher:

   ssh root@64.227.29.192 "python3 - <<PY
   import sqlite3
   c=sqlite3.connect('/opt/portal/portal.db')
   c.execute("UPDATE posts SET state='approved', scheduled=strftime('%Y-%m-%dT%H:%M:00Z','now','-1 minute') WHERE id=123")
   c.commit()
   PY"
   ssh root@64.227.29.192 python3 /opt/portal/publish_due.py

   Replace 123 with your post's ID.
3. The publisher prints the live URL(s) it created. Done.

Under the hood (for the technical reader)

publish_due.py selects state='approved' AND scheduled <= now, so setting the time in the past makes it eligible on the next run. The X daily cap and the PAUSE kill switch still apply.

Playbook 4 — Change how often it posts

Turn the posting rate up or down

Do it — step by step

1. Open the tenant config on the hub:

   ssh root@64.227.29.192 nano /opt/portal/clients.json

2. Find the account and change "cadence" (7 ≈ one a day; 14 ≈ two a day). Save (Ctrl+O, Enter) and exit (Ctrl+X).
3. Rebuild the queue (safe to run anytime):

   ssh root@64.227.29.192 python3 /opt/portal/generate.py

4. Check it with Playbook 9.

Under the hood (for the technical reader)

generate.py tops the queue up to cadence open posts, spread across the week's time slots, with least-recently-used rotation and a per-family cap for variety.

Playbook 5 — Add or remove a network for an account

Turn a channel on or off

Do it — step by step

1. Make sure the network is connected first (Playbook 1).
2. Edit the tenant config:

   ssh root@64.227.29.192 nano /opt/portal/clients.json

3. Set "channels" to the networks you want, e.g. ["x","bluesky"]. Drop "x" to go 100% free. Use ["dry"] to draft without sending anywhere (for testing). Save and exit.
4. Regenerate so new drafts carry the new channels:

   ssh root@64.227.29.192 python3 /opt/portal/generate.py

Under the hood (for the technical reader)

Playbook 6 — Change what a post says

Edit the wording (templates)

Do it — step by step

1. Open the templates file on the hub:

   ssh root@64.227.29.192 nano /opt/portal/portal_templates_wt.py

2. Each template is one line in the TEMPLATES list, shaped like:

   (kind, family, id, required fields, how to write it)
   ("site", "site_feature", "sf1", ["blurb","url"],
    lambda l, b: _cap("%s %s" % (_trim(l["blurb"],210), l["url"])))

   Change the wording inside the final part. Keep the %s placeholders and the fields listed in “required fields”.
3. Save and exit. Rebuild:

   ssh root@64.227.29.192 python3 /opt/portal/generate.py

4. Preview the result (Playbook 9) before it goes out.

Under the hood (for the technical reader)

Templates are deterministic (no AI call), so output is predictable and costs nothing to generate. A field can only be used if it's in the item's data — that's the honesty guard.

Playbook 7 — Add a whole new type of post

Create a new content family

Do it — step by step

1. Add the writing pattern. In portal_templates_wt.py, add one or more template lines with a new kind and family, listing the fields they need.
2. Supply the facts. In the feed builder on the main server (/root/gen-social-feed.py), add a section that reads your data and emits items tagged with that same kind and those fields.
3. Rebuild the feed and the queue:

   ssh root@143.198.182.180 python3 /root/gen-social-feed.py
   ssh root@64.227.29.192 python3 /opt/portal/generate.py

4. Preview (Playbook 9).

Under the hood (for the technical reader)

Keep the rule: emit an item only when every field its template needs is present. Missing field → the post is held, never guessed.

Playbook 8 — Refresh the content right now

Pull fresh data immediately

Do it — step by step

1. Rebuild the feed on the main server (this also ships it to the hub):

   ssh root@143.198.182.180 python3 /root/gen-social-feed.py

2. Rebuild the queue on the hub:

   ssh root@64.227.29.192 python3 /opt/portal/generate.py

3. Preview (Playbook 9).

Playbook 9 — See what's queued before it publishes

List the upcoming posts

Do it — step by step

1. Run this on the hub to print the pending/approved queue:

   ssh root@64.227.29.192 "python3 - <<PY
   import sqlite3
   c=sqlite3.connect('/opt/portal/portal.db'); c.row_factory=sqlite3.Row
   for r in c.execute("SELECT id,client,state,substr(scheduled,1,16) s,text FROM posts WHERE state IN ('pending','approved') AND scheduled>=datetime('now') ORDER BY scheduled"):
       print('#%d [%s/%s] %s'%(r['id'],r['client'],r['state'],r['s'])); print('   ',r['text'][:130])
   PY"

2. Each line shows the post ID (use it in other playbooks), the account, whether it's pending or approved, its time, and the text.

Playbook 10 — Stop everything instantly

The kill switch

Do it — step by step

1. Freeze:

   ssh root@64.227.29.192 touch /opt/portal/PAUSE

2. Nothing will publish while that file exists (the publisher checks for it first, every run).
3. Resume when ready:

   ssh root@64.227.29.192 rm /opt/portal/PAUSE

Playbook 11 — See what went out (and manage X spend)

Check results

Do it — step by step

1. See recent publishes and their URLs:

   ssh root@64.227.29.192 tail -n 40 /var/log/portal-pub.log

2. See the nightly feed build:

   ssh root@143.198.182.180 tail /var/log/social-feed.log

3. Failures also push a phone alert via ntfy, so you hear about problems without watching logs.

Manage X spend

Do it — step by step

1. To change the cap, edit X_DAILY_CAP near the top of /opt/portal/publish_due.py on the hub.
2. To post more to X, raise the cap and add funds in the X developer portal.
3. To stop paying X entirely, remove "x" from a tenant's channels (Playbook 5) — Bluesky keeps posting free.