CompleteNoobs - User contributions [en]

Hive Blockchain Create Custom Coins

2026-05-26T17:32:20Z

AwesomO: /* Exchanging tokens on an exchange */

{{:LICENCE_HEADER_CC0}}
= v4call — How to Create Your Own Custom Token (e.g. CNOOBS) on Hive Engine =
From CompleteNoobs
F
This guide walks you through creating a custom Hive Engine token (example: '''CNOOBS''') in under 10 minutes. No coding required.

These tokens power the custom communication economy in v4call: you can set rates like "1 CNOOBS = 1 text message" or "10 CNOOBS = 1 hour video call", gift them to friends/family, or let blocked users bypass your blocklist if they hold enough of your token.

'''Why create your own token?'''
* Full control over supply and distribution.
* Real utility inside v4call (and any other Hive dApp that supports Hive Engine tokens).
* Scarcity you decide — perfect for personal or community communication economies.
* Transferable, tradable, and giftable via Hive Keychain or TribalDex.

'''Cost''': Approximately 100 BEE (Hive Engine's utility token). BEE price fluctuates — check current value on TribalDex or PeakD. This is a one-time creation fee.

'''Source''': Based on the official Hive Engine / TribalDex interface (as of 2026).

'''End result''': A live custom token (e.g. CNOOBS) that appears in users' Hive Keychain wallets and can be used in your v4call rates post.

== Contents ==
* [[#What_You_Need|1 What You Need]]
* [[#Step_1:_Get_Some_BEE_Tokens|2 Step 1: Get Some BEE Tokens]]
* [[#Step_2:_Log_In_to_TribalDex|3 Step 2: Log In to TribalDex]]
* [[#Step_3:_Create_Your_Token|4 Step 3: Create Your Token]]
* [[#Step_4:_Issue_Tokens_to_Yourself|5 Step 4: Issue Tokens to Yourself]]
* [[#Step_5:_Optional_-_Add_Metadata_(Logo_Description)|6 Step 5: Optional - Add Metadata (Logo & Description)]]
* [[#Step_6:_Distribute_Your_Tokens|7 Step 6: Distribute Your Tokens]]
* [[#Using_Your_Token_in_v4call|8 Using Your Token in v4call]]
* [[#Common_Problems_and_Fixes|9 Common Problems and Fixes]]
* [[#Quick_Reference|10 Quick Reference]]

== What You Need ==
* A Hive account (e.g. @noblemage) with Hive Keychain installed and the '''active key''' available.
* Some BEE tokens (≈100 BEE for creation fee).
* A web browser.

You do '''not''' need to run a node or write code.

== Step 1: Get Some BEE Tokens ==
BEE is the "gas" token for Hive Engine actions.

# Go to [https://tribaldex.com tribaldex.com] or any Hive Engine market (e.g. via PeakD wallet).
# Swap or buy BEE using HIVE or HBD (very easy with Keychain).
# Alternative: Many users get small amounts of BEE from community airdrops or by swapping on the built-in market.

Make sure you have at least 110 BEE to cover the fee plus a small buffer.

== Step 2: Log In to TribalDex ==
# Visit [https://tribaldex.com/tokens/create https://tribaldex.com/tokens/create]
# Click the login button at the top.
# Hive Keychain will pop up — approve the login with your '''active key''' (or posting key in some cases, but active is safest for token actions).

You are now logged in as your Hive account.

== Step 3: Create Your Token ==
On the token creation form, fill in the following fields carefully. Most cannot be changed later.

* '''Symbol''' — e.g. '''CNOOBS''' (uppercase, 1–10 characters, unique)
* '''Name''' — e.g. '''Cnoobs Coins'''
* '''Max Supply''' — Choose a number (e.g. 1,000,000). This is the absolute maximum that can ever exist. You can issue less.
* '''Precision''' — Usually '''3''' (allows 0.001 precision). You can only increase this later, not decrease.
* '''Website''' (optional) — Link to your profile or v4call server (e.g. https://call.yourdomain.com)
* '''Description''' (optional) — Short text like "Personal communication token for v4call — used for messages and calls with @cnoobz"

Double-check everything — the symbol especially cannot be changed.

Click '''Create Token'''.

Hive Keychain will ask you to approve a custom_json transaction. Confirm it.

Wait 3–10 seconds for confirmation on the blockchain.

Success message should appear: your token is now created!

== Step 4: Issue Tokens to Yourself ==
After creation, you usually start with zero balance.

# Go to [https://tribaldex.com/tokens/manage https://tribaldex.com/tokens/manage]
# Find your new token (CNOOBS) in the list.
# Click the '''Issue''' button.
# Enter the amount you want to issue to yourself (e.g. 10000).
# Confirm with Keychain.

You now hold the full issued supply.

== Step 5: Optional — Add Metadata (Logo & Description) ==
# Still on the manage page, click the edit icon for your token.
# Upload a square logo image (recommended 200x200 px or larger).
# Improve the description and website link.
# Save changes (another small Keychain transaction).

This makes your token look professional when users view it in wallets or markets.

== Step 6: Distribute Your Tokens ==
* Send to friends/family via Keychain → "Tokens" tab → Transfer.
* Airdrop to your community.
* Use in v4call rates (see below).
* List on TribalDex market if you want people to buy/sell them.

Tokens are fully transferable and appear instantly in recipients' Hive Keychain wallets.

== Using Your Token in v4call ==
Once you have your token:

# Go to your v4call server → /rate-editor.html
# In the rate editor (V2 format), create a new list like [LIST:token-holders]
# Set TOKEN:CNOOBS
# Define rates, e.g.:
** TEXT:1 CNOOBS
** VOICE:RING:5 CNOOBS;CONNECT:10 CNOOBS;RATE:20 CNOOBS/hr
* Your server will automatically verify balances using public Hive Engine RPC when someone tries to call or message you.

Blocked users can bypass your blocklist if you set ALLOW-IF-TOKEN:CNOOBS and they hold enough.

== Exchanging tokens on an exchange ==
Its pretty simple - you can exchange with hive-engine.com
* https://hive-engine.com/trade/CNOOBS
<code>https://hive-engine.com/trade/<YOUR_TOKEN></code>

== Finding your tokens across the network ==

* https://he.dtools.dev/richlist/CNOOBS

== Common Problems and Fixes ==
=== "Not enough BEE" error ===
Buy or swap more BEE on TribalDex.

=== Token symbol already taken ===
Choose a different symbol (add numbers or make it longer, e.g. CNOOBS2).

=== Transaction fails ===
Make sure you are using the '''active key''' in Keychain for token creation/issuing. Restart Keychain if needed.

=== Can't find my token after creation ===
Refresh the page or check https://hive-engine.com/tokens — it may take a few seconds to appear.

=== Want to issue more later? ===
You can issue up to your max supply at any time from the manage page.

== Quick Reference ==
{| class="wikitable"
|-
! Action !! Where to Do It
|-
| Create token || https://tribaldex.com/tokens/create
|-
| Manage / Issue tokens || https://tribaldex.com/tokens/manage
|-
| View all tokens || https://hive-engine.com/tokens
|-
| Swap BEE || TribalDex market
|-
| Check balance in Keychain || Hive Keychain extension → Tokens tab
|}

'''Next step for v4call users''': After creating your token, update your v4call-rates post using the improved rate-editor.html to include your custom token rates and blocklist bypass.

You now have your own personal communication currency on Hive!

== Staking <b>UNTESTED</b> at current time ==
== Appendix A: Enabling Staking on an Existing Token (e.g. CNOOBS) ==
So you've created your token but forgot to enable staking? No problem — staking can be enabled on an existing Hive Engine token at any time. This appendix walks you through it.

'''Why enable staking?'''
* Lets holders "lock up" tokens for influence, rewards, or governance.
* Required if you ever want to add a reward pool (Scotbot/SMT) later — staking is a prerequisite.
* Useful in v4call: you can require holders to ''stake'' (not just hold) CNOOBS to bypass blocklists or unlock premium rates. Staked tokens can't be quickly dumped, so they prove genuine commitment.
* Adds scarcity — staked tokens are removed from the liquid circulating supply.

'''Cost''': Approximately '''1000 BEE''' (one-time burn fee). This is significantly more than the 100 BEE token creation fee, so make sure you actually want this feature before paying. The fee is non-refundable.

'''Important''': Enabling staking is generally a one-way action. Once enabled it cannot be disabled. Some parameters (like cooldown period) can be edited later, but the staking feature itself is permanent. Plan your tokenomics before pulling the trigger.

=== What You Need ===
* Your existing token (e.g. CNOOBS) created on Hive Engine.
* Your Hive account with Hive Keychain and the '''active key''' available.
* At least '''1010 BEE''' in your wallet (1000 for the fee + small buffer).
* A few minutes.

=== Step A1: Get 1000+ BEE ===
Same as before — swap HIVE/HBD for BEE on [https://tribaldex.com tribaldex.com] or buy BEE on the Hive Engine market. Make sure you have at least 1010 BEE liquid in your wallet (not staked) before continuing.

=== Step A2: Go to the Manage Tokens Page ===
# Visit [https://tribaldex.com/tokens/manage https://tribaldex.com/tokens/manage]
# Log in with Hive Keychain (active key) if not already logged in.
# Find your token (CNOOBS) in the list of tokens you own.

=== Step A3: Click "Enable Staking" ===
# Next to your token, look for the '''Enable Staking''' button or icon (sometimes shown as a lock/coin symbol). Depending on UI updates, it may be under an "Actions" or "More" menu.
# A form will appear with the following fields:

* '''Unstaking Cooldown (days)''' — How long it takes to unstake tokens once a holder requests it. Common values: 7, 14, 28, or 30 days. Longer = more commitment = more scarcity. For a personal communication token like CNOOBS, '''7 days''' is a reasonable starting point.
* '''Number of Transactions''' — How many payouts the unstake is split into. Example: 28 days over 4 transactions = the holder gets 25% of their unstaked tokens every 7 days. Common values: 1, 4, or matching the cooldown days.
* '''Enable Delegation''' (optional checkbox) — Lets users delegate (lend) staked tokens to others without unstaking. Highly recommended for v4call use cases (e.g. delegate CNOOBS to a friend so they can call you).
* '''Delegation Cooldown (days)''' (if delegation enabled) — How long after un-delegating before tokens return to the original staker. Usually 7 days.

'''Recommended starter settings for CNOOBS:'''
{| class="wikitable"
|-
! Field !! Suggested Value
|-
| Unstaking Cooldown || 7 days
|-
| Number of Transactions || 4 (= 25% every ~1.75 days)
|-
| Enable Delegation || Yes (checked)
|-
| Delegation Cooldown || 7 days
|}

# Double-check your settings — cooldown values can usually be edited later, but it costs additional small fees and confusion for holders.
# Click '''Enable Staking''' (or similar confirmation button).
# Hive Keychain will pop up asking you to approve a custom_json transaction that '''burns 1000 BEE'''. Confirm with your active key.
# Wait 3–10 seconds for blockchain confirmation.

Success! Staking is now live on your token.

=== Step A4: Verify Staking is Enabled ===
# Go to https://hive-engine.com/tokens
# Search for CNOOBS.
# Click the token — you should now see a "Stake" / "Unstake" / "Delegate" option visible to all holders.
# In your own Hive Keychain wallet, on the Tokens tab, CNOOBS should now show a small lock/stake icon next to the transfer button.

Try staking 10 CNOOBS yourself as a test — it should appear under "Staked Balance" immediately.

=== Step A5: Update v4call to Recognise Staked Tokens ===
Your v4call rate editor can distinguish between '''liquid''' and '''staked''' balances. Examples in V2 format:

[LIST:liquid-holders]
TOKEN:CNOOBS
TYPE:LIQUID
TEXT:1 CNOOBS

[LIST:committed-holders]
TOKEN:CNOOBS
TYPE:STAKED
MIN:100
TEXT:FREE
VOICE:FREE
ALLOW-IF-STAKED:CNOOBS:100

This means: anyone holding 100+ '''staked''' CNOOBS gets free messaging and bypasses the blocklist, while liquid holders pay normal rates. Staking proves long-term commitment, not just speculation.

=== Common Problems and Fixes (Staking) ===

==== "Insufficient BEE balance" ====
You need 1000+ BEE liquid (not staked). Buy/swap more on TribalDex.

==== "Enable Staking" button doesn't appear ====
* Make sure you're logged in as the token issuer (the account that created CNOOBS).
* Try a different Hive Engine RPC node — go to TribalDex settings and switch to a different node. Some nodes lag.
* Refresh and try again.

==== Transaction succeeds but staking doesn't activate ====
Wait 30–60 seconds and refresh — Hive Engine sometimes takes a moment to propagate. Check https://hive-engine.com/tokens to confirm.

==== Can I disable staking later? ====
Generally no — staking is a permanent feature once enabled. You ''can'' edit the cooldown period and delegation settings later (small Keychain transaction, no big fee), but the staking system itself stays on.

==== Can I add a reward pool now? ====
Yes — with staking enabled, you can now optionally pay another 1000 BEE for Scotbot/SMT to enable post curation rewards in CNOOBS. Not required for v4call use, but available if you want to grow a community around the token.

=== Updated Quick Reference ===
{| class="wikitable"
|-
! Action !! Cost (BEE) !! Where
|-
| Create token || 100 || tribaldex.com/tokens/create
|-
| Issue tokens || Free (gas only) || tribaldex.com/tokens/manage
|-
| '''Enable staking''' || '''1000''' || '''tribaldex.com/tokens/manage'''
|-
| Edit staking cooldown || ~Free (small fee) || tribaldex.com/tokens/manage
|-
| Enable Scotbot rewards (optional) || 1000 || tribaldex.com/smt/manage
|-
| View token info || Free || hive-engine.com/tokens
|}

'''Total cost so far for a staking-enabled CNOOBS''': ~1100 BEE (100 create + 1000 staking).

You now have a fully stakeable communication token — perfect for distinguishing committed v4call users from casual holders.

[[Category:Hive]]
[[Category:Hive Engine]]
[[Category:v4call]]
[[Category:Token Creation]]
[[Category:Web3]]

NGate

2026-05-26T00:40:51Z

AwesomO:

* nGate-dev

Stage 1: https://www.completenoobs.com/noobs/Nostr-relay-with-whitelist

Stage 2: https://www.completenoobs.com/noobs/Nostr-handson

Data: https://www.completenoobs.com/noobs/V4call-server-data-flow

https://www.completenoobs.com/noobs/Ngate_basic

https://www.completenoobs.com/noobs/Ngate-strfry-basic

Ngate-strfry-basic

2026-05-26T00:40:18Z

AwesomO: Created page with "{{:LICENCE_HEADER_MIT}} = strfry + nGate — A Hot-Reloading Whitelisted Nostr Relay on Ubuntu 24.04 = From CompleteNoobs This guide deploys a '''strfry''' Nostr relay at <code>nostr.v4call.com</code> on a fresh Ubuntu 24.04 server, behind TLS, with nGate driving a '''live, hot-reloading whitelist''' — the relay's allowed-publisher list is updated '''without ever restarting the relay'''. This is the "Stage 4" path described in CLAUDE.md / STATUS.md. It is..."

{{:LICENCE_HEADER_MIT}}

= strfry + nGate — A Hot-Reloading Whitelisted Nostr Relay on Ubuntu 24.04 =

From CompleteNoobs

This guide deploys a '''strfry''' Nostr relay at <code>nostr.v4call.com</code> on a fresh Ubuntu 24.04 server, behind TLS, with nGate driving a '''live, hot-reloading whitelist''' — the relay's allowed-publisher list is updated '''without ever restarting the relay'''.

This is the "Stage 4" path described in [[CLAUDE.md]] / [[STATUS.md]]. It is an '''alternative''' to the [[#nostr-relay-with-whitelist|nostr-rs-relay]] stage-1 deploy, not a replacement you must take. Read the comparison below before deciding.

This is a "noob doing Nostr by doing" walkthrough in the same style as the [[Nostr Relay With a 3-Key Whitelist]] guide. Every command can be copy-pasted exactly as shown. You do not need to know C++, Go, or Rust.

== Why strfry instead of nostr-rs-relay? ==

Both work. The difference is '''how the whitelist is updated'''.

{| class="wikitable"
! !! nostr-rs-relay (stage 1) !! strfry (this guide)
|-
| Whitelist lives in || <code>config.toml</code> <code>pubkey_whitelist = [...]</code> || a separate plain file the policy plugin reads
|-
| To change the whitelist || rewrite <code>config.toml</code> '''+ restart the container''' || rewrite the whitelist file — '''no restart'''
|-
| nGate apply phase || writes config.toml between BEGIN/END markers, runs <code>docker restart</code> || writes <code>whitelist.json</code> atomically; relay picks it up on the next event
|-
| Restart cap / sanity bound || needed (a restart loop would flap the relay) || restart cap becomes irrelevant — there is no restart
|-
| Downtime on whitelist change || ~1–3 s reconnect blip for every connected client || none — open connections stay up
|-
| Config format || TOML || strfry's own libconfig-style <code>strfry.conf</code> (NOT TOML)
|}

'''The headline:''' a strfry '''write-policy plugin''' is a small program strfry runs and pipes every incoming event to. The plugin decides accept/reject per event. Because the plugin re-reads the whitelist file on each event (cheap — it is tiny), the moment nGate rewrites that file the '''very next event''' is judged against the new list. No restart, no dropped client connections.

'''The tradeoff (be honest):'''
* The plugin runs '''once per inbound write event'''. It must be fast. Reading a small JSON file per event is fine; we add an mtime cache so it only re-parses when the file actually changes.
* strfry's config file is '''not''' TOML. If you already run nostr-rs-relay you cannot reuse <code>config.toml</code> — this is a parallel setup.
* nGate's <code>scan → verify → gate</code> phases are '''unchanged'''. Only the <code>apply</code> phase swaps backend (writes a whitelist file instead of config.toml + restart). This guide ships a small <code>ngate-strfry-apply.sh</code> for that; the 3-strike-miss / state machinery from <code>ngate-apply.sh</code> is a later port (see [[#Whats_deferred|What's deferred]]).

'''Answering the question "can strfry be a Docker image?"''' — '''Yes.''' strfry ships an official multi-stage <code>Dockerfile</code> in its source repo. You <code>docker build</code> it once on the box (Step 7) and run it from <code>docker compose</code> like any other service. There are also community-published images on registries; we build from source instead so you are running code you fetched from the official repo at a tag you chose (trust tradeoff — a prebuilt image is faster but you are trusting whoever pushed it).

== Contents ==

* [[#What_You_Need|1 What You Need]]
* [[#Step_1:_Create_and_Point_the_Server|2 Step 1: Create and Point the Server]]
* [[#Step_2:_Log_In_and_Harden|3 Step 2: Log In and Harden]]
* [[#Step_3:_Install_Docker|4 Step 3: Install Docker]]
* [[#Step_4:_Open_the_Firewall|5 Step 4: Open the Firewall]]
* [[#Step_5:_Project_Folder_Layout|6 Step 5: Project Folder Layout]]
* [[#Step_6:_Get_Your_Whitelisted_Keys_in_Hex|7 Step 6: Get Your Whitelisted Keys in Hex]]
* [[#Step_7:_Build_the_strfry_Docker_Image|8 Step 7: Build the strfry Docker Image]]
* [[#Step_8:_Write_strfry.conf|9 Step 8: Write strfry.conf]]
* [[#Step_9:_The_Write-Policy_Plugin|10 Step 9: The Write-Policy Plugin]]
* [[#Step_10:_Seed_the_Whitelist|11 Step 10: Seed the Whitelist]]
* [[#Step_11:_Caddy_for_TLS|12 Step 11: Caddy for TLS]]
* [[#Step_12:_docker-compose.yml|13 Step 12: docker-compose.yml]]
* [[#Step_13:_Start_It_Up|14 Step 13: Start It Up]]
* [[#Step_14:_Prove_the_Whitelist_Works|15 Step 14: Prove the Whitelist Works]]
* [[#Step_15:_Prove_Hot-Reload_Works|16 Step 15: Prove Hot-Reload Works (the whole point)]]
* [[#Step_16:_Wire_in_nGate|17 Step 16: Wire in nGate]]
* [[#Step_17:_Automate_It_with_cron|18 Step 17: Automate It with cron]]
* [[#Step_18:_Optional_.E2.80.94_Per-User_Whitelisting_via_nostr-announce|19 Step 18: Optional — Per-User Whitelisting via <code>nostr-announce</code>]]
* [[#Common_Problems_and_Fixes|20 Common Problems and Fixes]]
* [[#Whats_deferred|21 What's deferred]]
* [[#Tips_for_Noobs|22 Tips for Noobs]]

== What You Need ==

* '''A VPS''' running fresh '''Ubuntu 24.04''', 1 GB RAM minimum (2 GB comfortable — the strfry build is C++ and wants RAM to compile). Vultr, Hetzner, DigitalOcean, etc. If using Vultr, our [https://www.vultr.com/?ref=7704739 Vultr referral link] helps cover server costs.
* '''A domain/subdomain''' with DNS access — this guide uses <code>nostr.v4call.com</code>. Substitute your own everywhere you see it.
* '''Your whitelisted Nostr keys in hex''' (Step 6 shows conversion). At minimum: the operator's own key, so you don't lock yourself out.
* '''A terminal + SSH''' and about '''45–60 minutes''' (the strfry compile is the slow part — 5–15 min depending on the box).
* '''The nGate repo''' if you want the automated whitelist (Step 16). Without nGate this is still a perfectly good manually-managed hot-reload relay.

== Step 1: Create and Point the Server ==

# Create the Ubuntu 24.04 VPS in your provider's panel. Note its public IPv4 address.
# In your DNS provider, add an '''A record''': <code>nostr.v4call.com → <your VPS IP></code>. TTL 300 is fine.
# Wait for DNS to propagate. Check from your laptop:

dig +short nostr.v4call.com

When that prints your VPS IP, continue. (Caddy in Step 11 will not be able to get a TLS certificate until DNS resolves correctly, so don't skip this.)

== Step 2: Log In and Harden ==

ssh root@nostr.v4call.com

Basic hardening (same as the stage-1 guide — skip if you already have your own baseline):

apt update && apt upgrade -y
adduser noob
usermod -aG sudo noob
rsync --archive --chown=noob:noob ~/.ssh /home/noob
# then log out and back in as: ssh noob@nostr.v4call.com

From here on, run commands as the <code>noob</code> user with <code>sudo</code> where shown.

== Step 3: Install Docker ==

sudo apt update
sudo apt install -y ca-certificates curl git
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo $VERSION_CODENAME) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo usermod -aG docker $USER
newgrp docker

Verify:

docker --version
docker compose version

== Step 4: Open the Firewall ==

sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw --force enable
sudo ufw status

Only 22 (SSH), 80 and 443 are exposed. strfry's own port (7777) stays internal to the Docker network — Caddy is the only thing the public talks to.

== Step 5: Project Folder Layout ==

sudo mkdir -p /opt/nostr-relay
sudo chown -R $USER:$USER /opt/nostr-relay
cd /opt/nostr-relay
mkdir -p strfry-db policy caddy_data caddy_config

You will end up with:

/opt/nostr-relay/
├── docker-compose.yml (Step 12)
├── strfry.conf (Step 8)
├── Caddyfile (Step 11)
├── strfry/ (the cloned strfry source, for the image build — Step 7)
├── policy/
│ ├── whitelist-policy.sh (the write-policy plugin — Step 9)
│ └── whitelist.json (the live whitelist nGate rewrites — Step 10)
├── seed.toml (operator's always-allowed keys — Step 10)
├── strfry-db/ (LMDB event database — created by strfry)
├── caddy_data/ caddy_config/ (Caddy TLS state)
└── (nGate bits added in Step 16)

== Step 6: Get Your Whitelisted Keys in Hex ==

Nostr relays compare the '''hex''' form of a public key, not the bech32 <code>npub1...</code> form. Same key, different encoding. The whitelist file holds hex.

To convert an npub to hex, the easiest no-install option: open <code>public/nostr-gen.html</code> from the v4call repo in any browser — it has an npub↔hex converter and never sends anything over the network. Or with the <code>nak</code> CLI:

nak decode npub1yourkeyhere

Write down each whitelisted key's 64-character hex string. You need at least the '''operator's own key''' before first start, or you lock yourself out (same rule as nGate's <code>seed.toml</code> — see [[CLAUDE.md]] decision #6).

== Step 7: Build the strfry Docker Image ==

We build from the official source at a pinned tag so you know exactly what you are running.

<div class="toccolours mw-collapsible mw-collapsed">
'''Useful info for low-powered VPS builds — read this BEFORE you run <code>docker build</code>'''
<div class="mw-collapsible-content">

The strfry compile is C++ (<code>g++ -std=c++20 -O3</code>) and it is the single most resource-hungry thing in this whole guide. On a small VPS it can make the box go '''completely unresponsive''' — you can't even open a second SSH session. Here is what is actually happening and how to survive it.

'''It's RAM, not "CPU at 100%".''' Linux schedules CPU fairly, so a pegged CPU still lets <code>sshd</code> in (just slowly). What truly freezes a tiny box is '''memory exhaustion''': each <code>g++</code> process on strfry can need '''1–1.5 GB''', and strfry's Dockerfile compiles several files in parallel. On a 1 GB VPS with no swap you hit the OOM killer / heavy swapping, and that is what blocks new logins. '''The build looks frozen but usually isn't''' — a single <code>main.cpp</code> object can take minutes with no output. Don't <code>Ctrl-C</code> too early (the way you almost did).

'''There is no "limit build to 70% CPU" flag.''' This guide's build uses BuildKit (you'll see <code>[+] Building</code> with <code>docker:default</code>). BuildKit '''ignores''' <code>--cpu-quota</code> / <code>--cpus</code> / <code>--cpuset-cpus</code> during <code>docker build</code> — those flags only apply to <code>docker run</code> (runtime containers), not to the build. <code>nice docker build ...</code> also does nothing useful, because the compiler processes are children of <code>dockerd</code>/<code>containerd</code>, not of your <code>docker</code> CLI, so the renice doesn't propagate. The real levers are '''parallelism''' and '''swap''', not a CPU percentage.

'''Lever 1 — lower the compile parallelism (biggest win).''' strfry's <code>Dockerfile</code> contains a line like:

RUN --mount=type=cache,target=/build/.cache \
make -j4

<code>-j4</code> = up to 4 compilers at once = up to ~4–6 GB peak RAM. Edit it down before building:
* <code>make -j1</code> — serial. Slowest, but a 1 GB box survives it. Safest on the smallest VPS.
* <code>make -j2</code> — a sane middle ground if you have ≥2 GB RAM.

This one edit is what turns "box OOM-kills the compiler / freezes" into "slow but it finishes".

'''Lever 2 — add swap BEFORE you build.''' Even 2 GB of swap turns "unresponsive / OOM" into "sluggish but still loggable, and the build completes". The swap commands are right after this box — run them '''first'''.

sudo fallocate -l 2G /swapfile && sudo chmod 600 /swapfile && sudo mkswap /swapfile && sudo swapon /swapfile

'''Lever 3 — never lose your session.''' Start the build inside <code>tmux</code> (or <code>screen</code>) so a dropped connection or a lock-up doesn't kill the build or lock you out:

tmux new -s build # then run the build inside it
# Ctrl-b then d to detach; tmux attach -t build to come back

Also open your '''second SSH session before''' starting the build, not after — once the box is under memory pressure you may not be able to log in fresh.

'''Watch the right thing.''' In the second session run <code>htop</code> (<code>sudo apt install -y htop</code>) and watch the '''Mem / Swp''' bars and swap in/out, not just CPU%. Swap churning = it's RAM = the fix is lower <code>-jN</code> + more swap, exactly as above.

'''TL;DR for a small box:''' add swap → edit <code>make -j4</code> down to <code>-j1</code> (or <code>-j2</code> if ≥2 GB) → run the build inside <code>tmux</code> → watch <code>htop</code>'s memory line → be patient, a quiet build is normal.
</div>
</div>

cd /opt/nostr-relay
git clone https://github.com/hoytech/strfry.git strfry
cd strfry
git submodule update --init
# Pin to a release tag (check https://github.com/hoytech/strfry/releases for the latest)
git checkout 1.0.4
docker build -t strfry:1.0.4 .
cd /opt/nostr-relay

This compiles strfry inside Docker. It is the slow step — '''5–15 minutes''' and a chunk of RAM. If the build is killed (OOM) on a 1 GB box, add swap first:

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

then re-run <code>docker build</code>.

'''Now build the nGate-flavoured image (REQUIRED — do not skip).''' The official strfry image is built <code>FROM alpine</code>, which ships busybox <code>sh</code> only — '''no <code>bash</code>, no <code>jq</code>'''. The write-policy plugin in Step 9 needs both. If you run the stock <code>strfry:1.0.4</code> image, the relay starts and serves reads fine, but '''every publish fails with <code>error: internal error</code>''' because the plugin can't execute (you'd waste an hour finding that out — we did). Bake the two tools in with a three-line wrapper image. Create <code>/opt/nostr-relay/Dockerfile.relay</code>:

<pre>
FROM strfry:1.0.4
RUN apk add --no-cache bash jq
</pre>

Build it:

cd /opt/nostr-relay
docker build -t strfry-ngate:1.0.4 -f Dockerfile.relay .

'''From here on the relay image you run is <code>strfry-ngate:1.0.4</code>''' (the compose file in Step 12 uses it). The plain <code>strfry:1.0.4</code> image only exists as the base for this wrapper. (<code>busybox stat -c %Y</code> — which the plugin also uses — '''is''' supported by Alpine's busybox, so once <code>bash</code> + <code>jq</code> are present the Step 9 plugin runs unmodified.)

'''Shortcut (optional, trust tradeoff):''' community-prebuilt images exist on container registries. Using one skips the compile but means trusting whoever pushed it. For a relay that gates who can write, building from the official repo yourself is the safer default. If you do use a prebuilt image, pin it by digest, not <code>:latest</code>.

== Step 8: Write strfry.conf ==

strfry's config is '''not TOML''' — it is a libconfig-style format. Create <code>/opt/nostr-relay/strfry.conf</code>:

<pre>
# strfry.conf — nostr.v4call.com
db = "/app/strfry-db/"

dbParams {
maxreaders = 256
mapsize = 10995116277760
}

relay {
bind = "0.0.0.0"
port = 7777

# strfry tries to raise its open-file limit to 1,000,000 by default.
# Most VPS hosts cap well below that, so strfry aborts on startup
# ("Unable to set NOFILES limit ...") and crash-loops. 0 = "don't
# attempt to set the limit, inherit the container's" — host-independent
# and the right default here. THIS KEY MUST BE INSIDE relay { } —
# at the top level strfry silently ignores it (see Common Problems).
nofiles = 0

# We are behind Caddy; Caddy sets X-Forwarded-For. realIpHeader lets
# strfry log the true client IP instead of the docker network IP.
realIpHeader = "x-forwarded-for"

info {
name = "nostr.v4call.com"
description = "Whitelisted relay — write-gated by nGate, public read."
pubkey = ""
contact = ""
}

maxWebsocketPayloadSize = 131072
autoPingSeconds = 55

# ── The bit that matters ──────────────────────────────────────────
# writePolicy.plugin points at an executable strfry pipes every
# inbound EVENT to (one JSON object per line on stdin; the plugin
# replies with one JSON object per line on stdout). The plugin reads
# the live whitelist file on each event, so rewriting that file
# changes the policy WITHOUT restarting strfry.
writePolicy {
plugin = "/app/policy/whitelist-policy.sh"
}
}
</pre>

Notes:
* <code>db</code>, plugin path etc. are '''container-internal''' paths (<code>/app/...</code>). The compose file in Step 12 bind-mounts host folders onto them.
* Changing <code>strfry.conf</code> itself (e.g. the plugin '''path''') '''does''' need a strfry restart — but the whitelist '''data''' the plugin reads does not. That distinction is the whole point: config path = static, whitelist data = live.

== Step 9: The Write-Policy Plugin ==

Create <code>/opt/nostr-relay/policy/whitelist-policy.sh</code>. This is the program strfry runs. It reads one JSON line per event on stdin and must print one JSON line per event on stdout: <code>{"id":"<event id>","action":"accept"|"reject","msg":"..."}</code>.

It reads <code>whitelist.json</code> (a JSON array of hex pubkeys) fresh — but only re-parses when the file's mtime changes, so the hot path is a cheap stat, not a re-read, per event.

'''Prerequisite:''' this script needs <code>bash</code> and <code>jq</code> '''inside the relay container'''. Stock strfry (Alpine) has neither — that is exactly why Step 7 builds the <code>strfry-ngate:1.0.4</code> wrapper image. If publishes fail with <code>error: internal error</code>, you skipped that. Two filenames that are easy to confuse: <code>whitelist-policy.sh</code> is '''this script''' (the program strfry runs); <code>whitelist.json</code> is the '''data file''' it reads (Step 10, rewritten by nGate). There is no <code>whitelist-policy.json</code> — if you find one it's a stray, ignore/delete it.

<pre>
#!/usr/bin/env bash
# strfry write-policy plugin — whitelist gate with mtime-cached reload.
# Protocol: https://github.com/hoytech/strfry/blob/master/docs/plugins.md
# stdin : one JSON per line {"type":"new","event":{"id":..,"pubkey":..},...}
# stdout: one JSON per line {"id":"<event id>","action":"accept"|"reject","msg":".."}
set -eo pipefail

WL="${STRFRY_WHITELIST:-/app/policy/whitelist.json}"

cached_mtime=""
declare -A allow # hex pubkey -> 1

reload_if_changed() {
local m
m=$(stat -c %Y "$WL" 2>/dev/null || echo "")
[[ "$m" == "$cached_mtime" ]] && return 0
cached_mtime="$m"
allow=()
if [[ -s "$WL" ]]; then
while IFS= read -r hex; do
[[ -n "$hex" ]] && allow["${hex,,}"]=1
done < <(jq -r '.[]? // empty' "$WL" 2>/dev/null || true)
fi
# Stderr is strfry's plugin log — handy for "did the reload fire?"
echo "[whitelist-policy] reloaded: ${#allow[@]} key(s) from $WL" >&2
}

# Prime once so the first event isn't slowed by a cold load.
reload_if_changed

while IFS= read -r line; do
[[ -z "$line" ]] && continue
reload_if_changed

id=$(echo "$line" | jq -r '.event.id // empty')
pubkey=$(echo "$line" | jq -r '.event.pubkey // empty')
pubkey="${pubkey,,}"

if [[ -n "$pubkey" && -n "${allow[$pubkey]:-}" ]]; then
printf '{"id":"%s","action":"accept"}\n' "$id"
else
printf '{"id":"%s","action":"reject","msg":"blocked: not on relay whitelist"}\n' "$id"
fi
done
</pre>

Make it executable:

chmod +x /opt/nostr-relay/policy/whitelist-policy.sh

'''Why bash + jq?''' Zero extra runtime, and <code>jq</code> is already an nGate dependency so the mental model stays consistent across the project. For a very high-throughput public relay you would rewrite this in Go/Rust; for an nGated federation-discovery relay the event rate is low and bash is plenty. (If you find the per-event <code>jq</code> spawn too heavy at scale, that's the upgrade trigger — note it and move on; don't pre-optimise.)

== Step 10: Seed the Whitelist ==

Two files:

'''<code>seed.toml</code>''' — operator-managed, never auto-removed (same concept and filename as nGate stage 1, [[CLAUDE.md]] decision #6). One hex pubkey per line, <code>#</code> for comments:

# /opt/nostr-relay/seed.toml — operator's always-allowed keys
# Put YOUR key here before first start or you lock yourself out.
abc123...your64charhexkey...def

'''<code>policy/whitelist.json</code>''' — the live file the plugin reads. nGate rewrites this in Step 16. Until then, hand-seed it from your seed keys. A JSON array of hex strings:

<pre>
[
"abc123...your64charhexkey...def"
]
</pre>

For now they overlap by hand. Once nGate is wired (Step 16) it produces <code>whitelist.json</code> as <code>(seed.toml ∪ verified+gated discovered keys)</code> — the seed is always merged in so the operator can never be auto-evicted.

== Step 11: Caddy for TLS ==

Create <code>/opt/nostr-relay/Caddyfile</code>:

<pre>
nostr.v4call.com {
reverse_proxy nostr-relay:7777
}
</pre>

Caddy auto-obtains and auto-renews a Let's Encrypt certificate for the domain and reverse-proxies WebSocket traffic to strfry. (This is identical in spirit to the stage-1 nostr-rs-relay Caddyfile — only the upstream port differs: strfry uses 7777, nostr-rs-relay used 8080.)

== Step 12: docker-compose.yml ==

Create <code>/opt/nostr-relay/docker-compose.yml</code>:

<pre>
services:

nostr-relay:
image: strfry-ngate:1.0.4 # bash+jq wrapper from Step 7, NOT plain strfry:1.0.4
container_name: nostr-relay
restart: unless-stopped
command: relay
volumes:
- ./strfry.conf:/etc/strfry.conf:ro
- ./strfry-db:/app/strfry-db
- ./policy:/app/policy # plugin + whitelist.json (RW: nGate writes here)
expose:
- "7777"
networks:
- relaynet

caddy:
image: caddy:2-alpine
container_name: caddy
restart: unless-stopped
ports:
- "80:80"
- "443:443"
volumes:
- ./Caddyfile:/etc/caddy/Caddyfile:ro
- ./caddy_data:/data
- ./caddy_config:/config
depends_on:
- nostr-relay
networks:
- relaynet

networks:
relaynet:
driver: bridge
</pre>

Notes:
* strfry's default Dockerfile reads <code>/etc/strfry.conf</code> and the entrypoint takes a subcommand (<code>relay</code> to run the relay). If your pinned strfry tag uses a different default config path, check <code>docker run --rm strfry:1.0.4 --help</code> and adjust the bind-mount target — this is the #1 version-drift gotcha.
* The <code>./policy</code> mount is '''read-write''' (no <code>:ro</code>) because nGate rewrites <code>whitelist.json</code> inside it. The plugin script itself is operator-trusted code.
* No Docker socket is mounted and there is '''no restart command''' anywhere — that whole class of nGate machinery (restart cap, sanity bound, BEGIN/END markers) is simply not needed here.

== Step 13: Start It Up ==

cd /opt/nostr-relay
docker compose up -d
docker compose ps
docker compose logs -f caddy # watch the cert get issued (Ctrl-C to stop tailing)
docker compose logs -f nostr-relay # watch strfry start + the plugin's reload line

You should see, in the relay log, the plugin's <code>[whitelist-policy] reloaded: N key(s)</code> line on the first event (or at prime time). If Caddy logs a certificate error, re-check DNS (Step 1) — it cannot issue a cert until <code>nostr.v4call.com</code> resolves to this box.

== Step 14: Prove the Whitelist Works ==

Install the <code>nak</code> CLI on your laptop (or any machine):

go install github.com/fiatjaf/nak@latest

'''Accepted''' — publish with a key that IS in <code>whitelist.json</code>:

nak event -k 1 -c "hello from a whitelisted key" --sec <nsec-of-a-whitelisted-key> wss://nostr.v4call.com

You should get an OK / accepted response.

'''Rejected''' — publish with a fresh random key that is NOT whitelisted:

nak event -k 1 -c "i should be blocked" --sec $(nak key generate) wss://nostr.v4call.com

You should get a rejection carrying <code>blocked: not on relay whitelist</code> (the <code>msg</code> from the plugin).

'''Public read still works for everyone''' (whitelist gates writes only):

nak req -k 1 wss://nostr.v4call.com

== Step 15: Prove Hot-Reload Works (the whole point) ==

This is the demo that justifies the whole strfry switch.

# Pick a fresh key and confirm it is '''rejected''' (it's not whitelisted yet):
#: <code>NSEC=$(nak key generate); echo "$NSEC"</code>
#: <code>nak event -k 1 -c "before" --sec "$NSEC" wss://nostr.v4call.com</code> → rejected.
# Get that key's hex: <code>nak decode <the npub nak printed></code> (or it prints hex with <code>nak key public</code> flows).
# On the server, add the hex to the whitelist file '''with no restart''':
#: <code>cd /opt/nostr-relay/policy</code>
#: <code>jq '. + ["<newhex>"]' whitelist.json > whitelist.json.tmp && mv whitelist.json.tmp whitelist.json</code>
#: (the atomic <code>tmp</code> + <code>mv</code> is deliberate — never write the live file in place)
# Immediately re-publish with the same key:
#: <code>nak event -k 1 -c "after" --sec "$NSEC" wss://nostr.v4call.com</code> → '''now accepted'''.

No <code>docker restart</code>, no reconnect blip, open client connections never dropped. That is the entire reason this guide exists. The relay log shows a fresh <code>[whitelist-policy] reloaded: N key(s)</code> line the moment the file's mtime changed.

== Step 16: Wire in nGate ==

nGate's first three phases — <code>ngate-scan.sh</code> → <code>ngate-verify.sh</code> → <code>ngate-gate.sh</code> — are '''unchanged''' from the stage-3 walkthrough ([[nGate-auto-whitelist]]). They read Hive <code>v4call-server</code> posts, verify the Hive signature + Nostr attestation, apply the HP/token economic gate, and emit verified+gated NDJSON. Only the final '''apply''' phase differs: instead of rewriting <code>config.toml</code> and restarting (<code>ngate-apply.sh</code>), we atomically write <code>whitelist.json</code> and stop there.

'''Get nGate onto the box.''' Clone the repo into the project folder and install its Node crypto-helper dependencies (dhive + nostr-tools — the phase scripts shell out to them for Hive ECDSA / Nostr schnorr verification):

cd /opt/nostr-relay
git clone https://github.com/completenoobs/ngate.git nGate
sudo apt install -y npm
cd /opt/nostr-relay/nGate/scripts
npm install

(<code>npm install</code> reads <code>scripts/package.json</code> and populates <code>scripts/node_modules/</code>. Skip it and <code>ngate-verify.sh</code> dies the first time it verifies a signature — "cannot find module '@hiveio/dhive'".)

The strfry apply backend <code>ngate-strfry-apply.sh</code> '''ships in <code>nGate/scripts/</code>''' alongside the other phase scripts — you do '''not''' need to hand-create it. It is reproduced here for reference so you can see exactly what it does (seed-merge, atomic write, no restart):

<pre>
#!/usr/bin/env bash
# ngate-strfry-apply.sh — Stage-4 apply backend for strfry.
# Reads verified+gated NDJSON on stdin (same format ngate-apply.sh consumes),
# merges in seed.toml, atomically rewrites whitelist.json. NO restart needed —
# strfry's write-policy plugin re-reads the file live.
#
# ... | ngate-gate.sh | ./ngate-strfry-apply.sh --apply
#
# Defaults to --dry-run (nGate convention: write-side scripts need explicit --apply).
set -eo pipefail

DRY_RUN=true
[[ "${1:-}" == "--apply" ]] && DRY_RUN=false

WL="${NGATE_WHITELIST_PATH:-/opt/nostr-relay/policy/whitelist.json}"
SEED="${NGATE_SEED_PATH:-/opt/nostr-relay/seed.toml}"

declare -A keep

# 1. seed.toml — always merged, never auto-removed (CLAUDE.md decision #6)
if [[ -f "$SEED" ]]; then
while IFS= read -r raw; do
line="${raw%%#*}"; line="$(echo "$line" | tr -d '[:space:]')"
[[ -n "$line" ]] && keep["${line,,}"]=1
done < "$SEED"
fi

# 2. verified+gated discovered keys from stdin NDJSON
while IFS= read -r ev; do
[[ -z "$ev" ]] && continue
hex=$(echo "$ev" | jq -r '.nostr_pubkey_hex // empty' 2>/dev/null || true)
[[ -n "$hex" ]] && keep["${hex,,}"]=1
done

# 3. render sorted JSON array
new_json=$(printf '%s\n' "${!keep[@]}" | sort | jq -R . | jq -s .)

if [[ "$DRY_RUN" == "true" ]]; then
echo "DRY RUN — would write $(echo "$new_json" | jq 'length') key(s) to $WL" >&2
echo "$new_json"
exit 0
fi

# atomic write — strfry's plugin re-reads on mtime change, no restart
tmp="$(mktemp)"
echo "$new_json" > "$tmp"
mv "$tmp" "$WL"
echo "✓ wrote $(echo "$new_json" | jq 'length') key(s) to $WL (no restart)" >&2
</pre>

"The scripts are already executable from the clone. '''Run the chain manually first''' — nGate's safe default is dry-run, so this changes nothing yet:

cd /opt/nostr-relay/nGate/scripts
./ngate-scan.sh \
| ./ngate-verify.sh \
| NGATE_GATE_ACCOUNT=hive_account NGATE_MIN_TOKEN_SYMBOL=CNOOBS NGATE_MIN_TOKEN_AMOUNT=3 ./ngate-gate.sh \
| ./ngate-strfry-apply.sh

Read the output. <code>ngate-verify</code> prints one line per discovered server (<code>OK</code> / <code>REJECT</code> / <code>skip</code>); <code>ngate-gate</code> prints who passed the economic gate; the apply line says <code>DRY RUN — would write N key(s)</code>. The <code>REJECT … no nostr_attestation</code> and <code>skip … no nostr_pubkey_hex</code> lines for old / pre-Nostr announces are '''expected''' and correct ([[CLAUDE.md]] decision #1 — attestation required, no legacy compat), not errors.

'''When the dry-run looks right, apply for real''' (this is the exact command verified on <code>nostr.hive-book.com</code> — substitute your own gate thresholds):

cd /opt/nostr-relay/nGate/scripts
./ngate-scan.sh \
| ./ngate-verify.sh \
| NGATE_GATE_ACCOUNT=hive_account NGATE_MIN_TOKEN_SYMBOL=CNOOBS NGATE_MIN_TOKEN_AMOUNT=3 ./ngate-gate.sh \
| NGATE_MAX_CONSECUTIVE_MISSES=1 ./ngate-strfry-apply.sh --apply

Success looks like <code>✓ wrote N key(s) to /opt/nostr-relay/policy/whitelist.json (no restart)</code>. Confirm:

cat /opt/nostr-relay/policy/whitelist.json

It should hold your seed key (from <code>seed.toml</code>, always merged even though it is not on Hive — that is the point of the seed) '''plus''' one hex per verified+gated server. The relay picks it up on the very next event — '''no restart''' — and logs <code>[whitelist-policy] reloaded: N key(s)</code>.

''(Note the two flags shown: <code>--apply</code> turns off dry-run; add <code>--allow-removals</code> only when you want keys that have dropped off Hive to be pruned. Without <code>--allow-removals</code> the apply is ADD-only — safe against a transient Hive outage nuking your whitelist. <code>NGATE_MAX_CONSECUTIVE_MISSES</code> is carried for forward-compat with the deferred miss-counter — see [[#Whats_deferred|What's deferred]].)''

== Step 17: Automate It with cron ==

Manual runs prove it works; cron keeps it current. Every run recomputes the whitelist from Hive and atomically rewrites <code>whitelist.json</code> — '''no relay restart, ever''' — so running it often is cheap and safe.

'''Recommended: the explicit-env one-liner (this is the tested path).''' Edit your crontab:

crontab -e

Add (runs every 30 minutes; adjust the schedule — see the cheatsheet below):

<pre>
SHELL=/bin/bash
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

*/30 * * * * cd /opt/nostr-relay/nGate/scripts && flock -n /tmp/ngate.lock ./ngate-scan.sh | ./ngate-verify.sh | NGATE_GATE_ACCOUNT=hive_account NGATE_MIN_TOKEN_SYMBOL=CNOOBS NGATE_MIN_TOKEN_AMOUNT=3 ./ngate-gate.sh | NGATE_MAX_CONSECUTIVE_MISSES=1 ./ngate-strfry-apply.sh --apply --allow-removals >> /opt/nostr-relay/ngate-cron.log 2>&1
</pre>

'''Schedule cheatsheet''' (the five fields are <code>minute hour day-of-month month day-of-week</code>):

{| class="wikitable"
! Cron expression !! Runs
|-
| <code>*/15 * * * *</code> || every 15 minutes
|-
| <code>*/30 * * * *</code> || every 30 minutes
|-
| <code>0 * * * *</code> || every hour, on the hour
|-
| <code>0 */6 * * *</code> || every 6 hours
|-
| <code>0 3 * * *</code> || once a day at 03:00
|}

'''Three cron gotchas that bite everyone''' (noob-tested, in this guide's spirit):
* '''cron has almost no <code>PATH</code>.''' It does '''not''' inherit your login shell's environment, so <code>node</code>, <code>jq</code>, <code>git</code>, <code>flock</code> may not be found and the run silently does nothing. The <code>PATH=</code> line at the top of the crontab fixes this; if <code>node</code> lives somewhere odd (<code>which node</code> to check), add its directory to that <code>PATH=</code>.
* '''Always redirect to a log''' (<code>>> ... 2>&1</code>). Without it cron emails output into a local mailbox you'll never read, and a broken run is invisible. <code>tail -f /opt/nostr-relay/ngate-cron.log</code> after the first scheduled fire to confirm it ran clean.
* '''<code>flock -n</code> prevents overlap.''' A slow Hive scan that runs past the next tick would otherwise start a second copy on top of the first. <code>flock -n /tmp/ngate.lock</code> makes the new run bail if one is already going. (<code>flock</code> is from <code>util-linux</code>, present on Ubuntu by default.)

'''Alternative: drive the gate config from <code>ngate.yaml</code> instead of inline env vars.''' nGate ships <code>ngate.yaml.example</code> and a loop wrapper <code>ngate-sync.sh</code> that reads the YAML and translates it into the same <code>NGATE_*</code> env vars. '''Caveat — be honest about this:''' the stock <code>ngate-sync.sh</code> is hardwired to the stage-1 <code>ngate-apply.sh</code> (config.toml + restart), '''not''' the strfry backend. Until a strfry-aware sync wrapper lands (tracked under [[#Whats_deferred|What's deferred]]), the clean way to get YAML-driven config on a strfry box is a tiny shim that reads the gate keys out of <code>ngate.yaml</code> with <code>yq</code> and feeds the strfry pipeline:

<pre>
#!/usr/bin/env bash
# /opt/nostr-relay/nGate/scripts/ngate-strfry-cron.sh
# YAML-driven one-shot for the strfry backend. Point cron at THIS instead of
# the long inline pipeline if you'd rather keep gate config in ngate.yaml.
set -eo pipefail
cd "$(dirname "$0")"
Y="${NGATE_YAML:-/opt/nostr-relay/ngate.yaml}"

GA=$(yq -r '.gate.account // "hive_account"' "$Y")
TS=$(yq -r '.gate.min_token_symbol // ""' "$Y")
TA=$(yq -r '.gate.min_token_amount // 0' "$Y")
MM=$(yq -r '.max_consecutive_failures // 1' "$Y")

./ngate-scan.sh \
| ./ngate-verify.sh \
| NGATE_GATE_ACCOUNT="$GA" NGATE_MIN_TOKEN_SYMBOL="$TS" NGATE_MIN_TOKEN_AMOUNT="$TA" ./ngate-gate.sh \
| NGATE_MAX_CONSECUTIVE_MISSES="$MM" ./ngate-strfry-apply.sh --apply --allow-removals
</pre>

chmod +x /opt/nostr-relay/nGate/scripts/ngate-strfry-cron.sh

Then the crontab line collapses to:

<pre>
*/30 * * * * flock -n /tmp/ngate.lock /opt/nostr-relay/nGate/scripts/ngate-strfry-cron.sh >> /opt/nostr-relay/ngate-cron.log 2>&1
</pre>

This shim is '''not''' tested end-to-end the way the explicit-env pipeline above is — review it and dry-run it once (drop <code>--apply</code>) before trusting it on a schedule. The explicit-env crontab line is the path this guide has actually run in production; the YAML shim is offered as the tidier option once you've verified it on your box. (<code>yq</code> here is mikefarah's Go <code>yq</code> or kislyuk's Python <code>yq</code> — both handle these <code>.field // default</code> queries; <code>sudo apt install -y yq</code> or grab the mikefarah release binary.)

'''Alternative: a compose sidecar instead of cron.''' If you'd rather not use cron, add an nGate sidecar service to <code>docker-compose.yml</code> the same way stage 1 did (a long-running container that loops the pipeline), but its volume mount is just <code>./policy</code> (read-write, so it can write <code>whitelist.json</code>) and <code>./seed.toml</code> — '''no Docker socket''', because nGate no longer needs to restart any container. That removes the single biggest security caveat of the stage-1 sidecar (mounting <code>/var/run/docker.sock</code> gave the sidecar effective host root).

== Step 18: Optional — Per-User Whitelisting via <code>nostr-announce</code> ==

Everything up to Step 17 whitelists '''servers''' (one Hive post per v4call server, tagged <code>v4call-server</code>, scanned by <code>ngate-scan.sh</code>). This optional step adds a '''second parallel pipeline''' that whitelists '''individual users''' who publish a per-user Nostr-identity binding to Hive (one post per user, tagged <code>nostr-announce</code>, scanned by <code>ngate-user-scan.sh</code>). Both pipelines write to the same <code>policy/whitelist.json</code> — the strfry plugin doesn't care which pipeline added a key.

'''Skip this step entirely''' if you only want server-tier whitelisting. The federation-discovery relay works perfectly without per-user gating; this is a separate use case (e.g. "anyone holding ≥3 CNOOBS can publish to my relay"), not a v4call-fed requirement.

'''The user-facing tool''' that produces these posts ships in the v4call repo: '''<code>public/nostr-announce.html</code>''' ([https://github.com/CompleteNoobs/v4call/blob/main/public/nostr-announce.html source on GitHub], normally served at <code>https://your-v4call-server.com/nostr-announce.html</code>). A user opens the page, fills in their Hive account, pastes their Nostr <code>nsec</code> (which never leaves their browser), clicks '''Sign attestation''' — the page builds a kind-30078 Nostr event with the Hive account in a tag, signs it with the nsec entirely in-browser, embeds it (base64) in a Hive post titled <code>nostr-announce</code>, and broadcasts the post via Hive Keychain or a pasted Hive posting key. The nsec is wiped on a successful broadcast. The result is a Hive post whose body contains a <code>[V4CALL-NOSTR-BINDING-V1]</code> block — that's what nGate's user-side pipeline reads.

=== What this pipeline does ===

Per scheduled run (defaults: every 30 min via cron, exactly like the server pipeline):
# '''<code>ngate-user-scan.sh</code>''' hits Hive RPC for the latest posts tagged <code>nostr-announce</code>, parses each <code>[V4CALL-NOSTR-BINDING-V1]</code> block, emits one NDJSON candidate per line. Read-only.
# '''<code>ngate-user-verify.sh</code>''' base64-decodes each candidate's attestation, cryptographically verifies the kind-30078 Nostr event ('''same <code>lib/ngate-verify-nostr-event.mjs</code> helper used by the server pipeline'''), and asserts: <code>event.pubkey</code> matches the declared hex; <code>d</code>-tag is <code>v4call-nostr-binding</code>; <code>v4call_hive_account</code> tag matches '''both''' the post author '''and''' the body's <code>HIVE-ACCOUNT</code> field. Only passing rows go downstream. Read-only.
# '''<code>ngate-gate.sh</code>''' (existing, unchanged) reads the rows on stdin, looks up each <code>hive_account</code>'s HP and/or token balance via Hive RPC + Hive-Engine, and lets through only those that meet the configured thresholds. Read-only.
# '''<code>ngate-strfry-apply.sh</code>''' (existing, unchanged) merges the surviving hexes with <code>seed.toml</code>, atomically rewrites <code>policy/whitelist.json</code>, no restart. The plugin re-reads on mtime change at the very next event.

The two scan/verify scripts mirror the existing <code>ngate-scan.sh</code> / <code>ngate-verify.sh</code> in style, dependencies, NDJSON shape, and exit codes. The downstream <code>ngate-gate.sh</code> and <code>ngate-strfry-apply.sh</code> are completely untouched — '''zero risk to your existing v4call-server pipeline''' from adding this step.

=== Verify the scripts exist (after the next nGate pull) ===

cd /opt/nostr-relay/nGate
git pull
ls scripts/ngate-user-scan.sh scripts/ngate-user-verify.sh

If they're missing, your local nGate clone is behind <code>main</code>. <code>git pull</code> in <code>/opt/nostr-relay/nGate</code> updates them. No <code>docker</code> rebuild needed — the nGate scripts run on the host, not inside the relay container.

=== Smoke-test (read-only, no whitelist write) ===

See what's currently discoverable without touching the whitelist:

cd /opt/nostr-relay/nGate/scripts
./ngate-user-scan.sh | ./ngate-user-verify.sh | jq -c .

Expected: zero or more NDJSON lines on stdout (each a verified per-user binding) plus chatty stderr from the scan and verify phases (<code>OK @user/permlink — …</code> or <code>REJECT …</code> with a clear reason).

=== Dry-run the full pipeline with a real gate ===

Add the gate you want — example below is "must hold ≥3 CNOOBS on the Hive account that signed the post":

cd /opt/nostr-relay/nGate/scripts
./ngate-user-scan.sh | ./ngate-user-verify.sh | \
NGATE_GATE_ACCOUNT=hive_account NGATE_MIN_TOKEN_SYMBOL=CNOOBS NGATE_MIN_TOKEN_AMOUNT=3 \
./ngate-gate.sh | \
./ngate-strfry-apply.sh # dry-run (default; nGate convention)

The last line ends with <code>DRY-RUN: would write N key(s) to /opt/nostr-relay/policy/whitelist.json</code>. Read the gate log lines on stderr to confirm the right accounts passed/failed before you go live.

=== Schedule it (test relay first) ===

Add to <code>crontab -e</code>, '''same box, separate lock file and log''' so it never blocks the existing v4call-server cron and so diagnostics stay clean:

<pre>
# nostr-announce per-user pipeline — runs every 30 min, parallel to the v4call-server one
*/30 * * * * cd /opt/nostr-relay/nGate/scripts && flock -n /tmp/ngate-user.lock bash -c './ngate-user-scan.sh | ./ngate-user-verify.sh | NGATE_GATE_ACCOUNT=hive_account NGATE_MIN_TOKEN_SYMBOL=CNOOBS NGATE_MIN_TOKEN_AMOUNT=3 ./ngate-gate.sh | NGATE_MAX_CONSECUTIVE_MISSES=1 ./ngate-strfry-apply.sh --apply --allow-removals' >> /opt/nostr-relay/ngate-user-cron.log 2>&1
</pre>

'''Two new things in this line vs the v4call-server cron:'''
* '''<code>/tmp/ngate-user.lock</code>''' (not <code>/tmp/ngate.lock</code>) — separate flock so the user-scan can run alongside the server-scan; one slow Hive node won't make the other pipeline skip its turn.
* '''<code>ngate-user-cron.log</code>''' — separate log file makes "did the user gate prune anyone today?" a one-line <code>grep</code> instead of digging through interleaved server-side noise.

'''<code>--allow-removals</code> tells the apply step it's OK to remove keys that no longer pass the gate''' (e.g. a user dropped below 3 CNOOBS). Without it, the whitelist is ADD-only — that's deliberately the safer default but you almost certainly want removals on for a per-user economic gate. Pair with <code>NGATE_MAX_CONSECUTIVE_MISSES=1</code> so a single transient Hive-RPC error doesn't auto-evict — the row has to be genuinely missing on two consecutive runs to drop.

=== Test relay → production rollout discipline ===

Same posture as the v4call-server pipeline: '''don't add this cron line to a production relay until the test relay has run it cleanly for at least a few cycles.''' Watch <code>tail -f /opt/nostr-relay/ngate-user-cron.log</code>, watch the strfry log for the plugin's <code>[whitelist-policy] reloaded: N key(s)</code> lines, and confirm new keys show up in <code>cat /opt/nostr-relay/policy/whitelist.json</code> only when you expect them to.

=== What this step does NOT do ===

Honest scope:
* '''Does not change the strfry policy plugin.''' The plugin still only checks "is this pubkey in the whitelist?" Per-user and per-server keys are indistinguishable to it. If you want different gating rules per source you'd need a smarter plugin and a second whitelist file — not done here.
* '''Does not enforce kind restrictions.''' A whitelisted user can publish kind 1, kind 30078, kind anything to your relay. Gating happens at identity, not content. If you want a kind allowlist on top, that's a plugin-level change, not a whitelist-data change.
* '''Does not edit any of the existing pipeline scripts.''' Step 16's <code>ngate-scan.sh</code> / <code>ngate-verify.sh</code> / <code>ngate-gate.sh</code> / <code>ngate-strfry-apply.sh</code> are byte-identical to before. This is purely additive.
* '''Does not run inside the relay container.''' The nGate scripts run on the host via cron, write the whitelist file via the bind-mounted <code>./policy</code> directory. The strfry container only reads — no Docker socket needed, no relay-restart needed, no image rebuild needed.

== Common Problems and Fixes ==

''(Several of these were hit and fixed during the first real deploy of this guide to <code>nostr.hive-book.com</code> — they are reproducible first-boot traps, not edge cases. If you're following along on a fresh box you will probably meet the first three.)''

;strfry crash-loops with <code>Unable to set NOFILES limit to 1000000, exceeds max of 524288</code>
:strfry tries to raise its open-file limit to 1,000,000 on startup; almost every VPS caps lower, so the <code>setrlimit</code> fails, you see <code>atexit</code>, and the container restarts forever. The relay '''log will say <code>CONFIG: successfully installed</code> right before the error''' — that is a red herring; the config parsed, the limit call is what failed. '''Fix:''' set <code>nofiles = 0</code> '''inside the <code>relay { }</code> block''' of <code>strfry.conf</code> (Step 8 already does this in the current guide). <code>0</code> = "inherit the container's limit, don't try to raise it" — host-independent.
:'''The subtle part:''' <code>nofiles</code> is '''only''' read inside <code>relay { }</code>. If you put it at the '''top level''' of <code>strfry.conf</code> (a natural mistake), strfry's tolerant parser still prints <code>CONFIG: successfully installed</code> but '''silently ignores the key''' and keeps the built-in 1,000,000 default — so 0, 524288, and anything in between all behave identically (still crashing). If you tried several values and "nothing changed", this is why: wrong scope, not wrong value. Verify the running container's view with <code>docker compose run --rm --entrypoint sh nostr-relay -c 'grep -n nofiles /etc/strfry.conf'</code> '''and''' confirm the line sits under <code>relay {</code>.

;Edited <code>strfry.conf</code> but the old behaviour persists / logs show old timestamps
:strfry reads its config '''once, at process start''' — it does not watch the file. A bind-mounted config change is not picked up by a still-running (or merely <code>restart</code>ed) container, and a crash-looping container may have read the old file before you edited it. '''Always''' apply config changes with <code>docker compose up -d --force-recreate nostr-relay</code>, then read '''fresh''' log lines: <code>docker compose logs --since 2m -f nostr-relay</code>. Check the timestamps are newer than your edit — debugging against stale log output wastes a lot of time. (This is the opposite of the '''whitelist''' file, which the plugin re-reads live — see "Whitelist change didn't take effect" below. Config = static-at-start; whitelist data = live.)

;<code>nak ... status 502</code> / clients can't connect, "failed to connect to any of the given relays"
:A <code>502 Bad Gateway</code> from your domain means '''Caddy is up but its upstream (the strfry container) is not listening''' — almost always because strfry is crash-looping (see the NOFILES entry above). '''Fix strfry first; the 502 disappears on its own.''' Don't debug the 502 as a separate problem until <code>docker compose ps</code> shows <code>nostr-relay</code> as a stable <code>Up</code> (not restarting). Only if strfry is confirmed <code>Up</code> '''and''' you still get 502 is it a real proxy issue — then check the Caddyfile upstream name/port (<code>nostr-relay:7777</code>) and that both services share the compose network.

;<code>nak event</code> succeeds to send but the relay replies <code>msg: error: internal error</code> (reads work, writes fail)
:The write-policy plugin can't execute. The official strfry image is <code>FROM alpine</code> — busybox <code>sh</code> only, '''no <code>bash</code>, no <code>jq</code>'''. The Step 9 plugin is bash (associative arrays, <code>${var,,}</code>, process substitution) and calls <code>jq</code>, so inside stock strfry the kernel can't even exec it and strfry returns its generic <code>internal error</code> for every write. Reads work because the plugin is only invoked on writes. '''Confirm:''' <code>docker compose exec nostr-relay sh -lc 'which bash; which jq'</code> — both empty. '''Fix:''' build and run the <code>strfry-ngate:1.0.4</code> wrapper image from Step 7 (<code>apk add --no-cache bash jq</code>) and set <code>image: strfry-ngate:1.0.4</code> in compose (Step 12), then <code>docker compose up -d --force-recreate nostr-relay</code>. Re-test: a whitelisted key now publishes <code>success.</code>, a non-whitelisted key gets <code>blocked: not on relay whitelist</code> (the plugin's own message — proof it's running).

;"Nothing changed in the whitelist" but the apply log said it wrote keys
:Almost always a filename mix-up. <code>ngate-strfry-apply.sh</code> writes '''<code>whitelist.json</code>'''. The plugin script is '''<code>whitelist-policy.sh</code>'''. There is no <code>whitelist-policy.json</code> — if you <code>cat</code> that you're reading a stray/old file (delete it). Trust the apply script's own last line: <code>✓ wrote N key(s) to /opt/nostr-relay/policy/whitelist.json</code> — <code>cat</code> '''that exact path'''.

;Doubled log lines in <code>docker compose logs</code>
:Usually a stray leftover container from an earlier <code>docker compose run --rm</code> one-off running alongside the real service. <code>docker compose ps -a</code>; if you see a <code>...-run-...</code> container, <code>docker compose down && docker compose up -d</code> to clean. If only one container shows and lines are still doubled, it's just loguru writing to stderr that compose echoes — harmless.

;Caddy can't get a cert
:DNS for <code>nostr.v4call.com</code> isn't resolving to this box yet. <code>dig +short nostr.v4call.com</code> must return the VPS IP. Wait, re-check, restart Caddy.

;Every event is rejected, even whitelisted keys
:(a) <code>whitelist.json</code> holds '''npub''', not hex — the plugin compares hex. Convert (Step 6). (b) Hex case mismatch — the plugin lowercases both sides, so this shouldn't bite, but double-check the file has no stray quotes/commas (<code>jq . whitelist.json</code> must parse). (c) The <code>./policy</code> mount path inside the container doesn't match <code>strfry.conf</code>'s <code>writePolicy.plugin</code> path.

;strfry won't start / "config file not found"
:Your pinned strfry tag expects the config at a different path than <code>/etc/strfry.conf</code>. Run <code>docker run --rm strfry:1.0.4 --help</code>, find the expected path, fix the bind-mount target in compose. Pin a known tag; don't track <code>master</code>.

;Plugin "permission denied" in the relay log
:<code>chmod +x /opt/nostr-relay/policy/whitelist-policy.sh</code>. Also confirm it has a valid shebang and Unix line endings (<code>file whitelist-policy.sh</code> should not say "CRLF").

;LMDB / database permission errors
:Same class of issue as the stage-1 nostr-rs-relay SQLite UID gotcha. strfry's container user must be able to write <code>/app/strfry-db</code>. Quick fix on a single-purpose box of public events: <code>chmod -R 777 /opt/nostr-relay/strfry-db</code>. Cleaner fix: <code>chown</code> to the container's UID.

;Whitelist change didn't take effect
:The plugin reloads on '''mtime change'''. If you edited in place with an editor that preserves mtime (rare) or wrote without changing the file, touch it: <code>touch /opt/nostr-relay/policy/whitelist.json</code>. Always use the atomic <code>tmp</code> + <code>mv</code> pattern (as <code>ngate-strfry-apply.sh</code> does) — it guarantees a new mtime and never exposes a half-written file to the plugin.

;Build killed (OOM) on a small VPS
:Add swap (Step 7) and rebuild. The C++ compile is the only memory-hungry part; once the image exists, runtime RAM is small.

;<code>ngate-user-scan.sh</code> finds posts but <code>ngate-user-verify.sh</code> rejects '''every one''' with "attestation v4call_hive_account tag ≠ post author"
:The post was authored by one Hive account but its body's attestation tags name a different Hive account. Usually means somebody copy-pasted the body of someone else's <code>nostr-announce</code> post into their own draft and re-posted under their own account — the Nostr signature is still valid (the original signer's nsec produced it) but the tag no longer matches the new author, so the bind is broken on purpose. This is '''the system working''' — a real binding requires the original signer to publish under '''their own''' Hive account. Tell the user to re-sign in <code>nostr-announce.html</code> using their own Hive account + their own nsec, then re-post.

;<code>ngate-user-verify.sh</code> rejects a post with "attestation v4call_hive_account tag ≠ body HIVE-ACCOUNT field"
:The post body's <code>HIVE-ACCOUNT:</code> line says <code>alice</code> but the signed attestation inside it names <code>bob</code>. Same class as above — usually a copy-paste mistake or an attempt to fool a casual reader who only skims the body. The verify rejects on the cryptographic tag, not the human-readable body line, so this never reaches the whitelist. Re-sign in <code>nostr-announce.html</code> with the correct Hive account in the form field, the page generates a fresh attestation, post again.

;<code>ngate-user-verify.sh</code> says "missing nostr_pubkey_hex or nostr_attestation_b64"
:The post body is missing one of the required fields in the <code>[V4CALL-NOSTR-BINDING-V1]</code> block. Almost always because the user posted manually via peakd.com / hive.blog instead of using <code>nostr-announce.html</code> and forgot a line. Easiest fix: use the tool — it builds the block correctly every time.

;User gets <code>Post failed: unknown error</code> in <code>nostr-announce.html</code>
:Almost never a v4call/nGate bug. Two Hive-side causes: (a) Hive enforces a '''~5 minute gap between posts from the same account''' — if the user posted anything (this binding, a regular post, anything) less than 5 min ago, the broadcast fails. Wait, retry. (b) '''Low Resource Credits''', especially on fresh accounts with no staked Hive Power — check at <code>https://hivestats.io/@username</code>. Browser DevTools Console shows the full Hive response which usually carries the actual reason.

== What's deferred ==

Honest scope notes, so nobody is surprised later:

* '''3-strike miss tolerance + state.json''' — <code>ngate-apply.sh</code> (stage 1) tolerates a key being briefly missing from Hive for N cycles before removing it ([[CLAUDE.md]] decision #4), tracked in <code>state.json</code>. The minimal <code>ngate-strfry-apply.sh</code> above is '''recompute-fresh each run''' (seed ∪ current verified+gated set). That is safe and matches nGate's "Hive is source of truth, ADD-only on partial failure" philosophy '''only if''' you keep nGate's existing ADD-only guard in <code>ngate-sync.sh</code> (don't pass <code>--allow-removals</code> on a partial upstream failure). Porting the full miss-counter/state machinery to the strfry backend is a follow-up, not done here.
* '''Restart cap / sanity bound''' — intentionally '''dropped''', not ported. There is no restart, so a restart loop is impossible by construction. The sanity bound (refuse to empty the whitelist on garbage upstream) is still worth porting later as a guard against a bad scan nuking the file; for now the seed-merge means the operator's own key always survives.
* '''High-throughput plugin''' — bash+jq per event is fine for a low-rate federation-discovery relay. If this relay ever becomes a busy public one, rewrite the plugin in Go/Rust. Note it; don't pre-optimise.

These are tracked against Stage 4 in [[STATUS.md]].

== Tips for Noobs ==

* '''The plugin is just a program that answers yes/no per event.''' If you can write a shell script, you can write a strfry policy. Test it by hand: <code>echo '{"type":"new","event":{"id":"x","pubkey":"abc"}}' | ./policy/whitelist-policy.sh</code> should print an accept/reject line.
* '''Atomic writes always.''' Any time something rewrites <code>whitelist.json</code> — nGate, you by hand, a cron — write to a temp file then <code>mv</code>. <code>mv</code> on the same filesystem is atomic; the plugin never sees a half-file, and mtime always bumps so the reload fires.
* '''seed.toml is your seatbelt.''' Put your own key there before first start. Even if every scan fails forever, you can still publish.
* '''Read is public, write is gated.''' That's the model. Anyone can read your relay's events; only whitelisted keys can write. If you want private reads too, that's a different (and more complex) NIP-42 auth setup — out of scope here.
* '''strfry ≠ nostr-rs-relay config.''' Don't copy a <code>config.toml</code> across. Different daemon, different config language. The only thing that carries over conceptually is "a list of allowed hex pubkeys" — and now that list is a live file, not a restart-on-change config block.
* '''Keep the strfry tag pinned.''' <code>strfry:1.0.4</code>, not <code>strfry:latest</code>. When you choose to upgrade, do it deliberately: bump the tag, <code>git checkout</code> the new release, rebuild, test Step 14 + 15 again.

----
''Part of the v4call / nGate documentation set. See also: [[Nostr Relay With a 3-Key Whitelist]] (stage 1, nostr-rs-relay), [[nGate-auto-whitelist]] (stage 3, the scan→verify→gate→apply pipeline), [[V4call]] (the platform this federation-discovery layer serves).''

Ngate basic

2026-05-26T00:38:07Z

AwesomO: Created page with "{{:LICENCE_HEADER_MIT}} = nGate — Deploy to a Fresh Ubuntu 24.04 Server = From CompleteNoobs This guide walks an operator through deploying nGate on top of an existing stage-1 nostr-rs-relay running on a Vultr Ubuntu 24.04 box. After this you'll have: * The relay still running as before. * Caddy still terminating TLS as before. * '''A new sidecar container''' (<code>ngate-sync</code>) running alongside, scanning Hive every..."

{{:LICENCE_HEADER_MIT}}

= nGate — Deploy to a Fresh Ubuntu 24.04 Server =

From CompleteNoobs

This guide walks an operator through deploying nGate on top of an existing
[[Nostr_Relay_With_a_3-Key_Whitelist|stage-1 nostr-rs-relay]] running on a
Vultr Ubuntu 24.04 box. After this you'll have:

* The relay still running as before.
* Caddy still terminating TLS as before.
* '''A new sidecar container''' (<code>ngate-sync</code>) running alongside,
scanning Hive every 6 hours, updating the relay's <code>pubkey_whitelist</code>
automatically when v4call-server operators announce themselves.
* '''Cryptographic enforcement''': only posts that prove ownership of both
the Hive account AND the Nostr key (via mutual attestation) get whitelisted.

== Prerequisites ==

You've already:

* Followed [[Nostr_Relay_With_a_3-Key_Whitelist|stage 1]] and have a working
<code>wss://nostr.YOUR-DOMAIN/</code> relay.
* Followed [[Nostr_Hands-On|stage 2]] enough to be comfortable with the
Nostr protocol fundamentals.
* Have at least one v4call-server announce post on Hive (signed via
<code>server-sign.html</code>, announced via <code>server-announce.html</code>)
to use as test input.

If you don't have a v4call-server post yet, you can still deploy nGate and
test it (the scan will find existing operators' posts), you just won't be in
the whitelist until you publish your own.

== Contents ==

* [[#Step_1:_SSH_to_the_relay_box|1 Step 1: SSH to the relay box]]
* [[#Step_2:_Install_runtime_dependencies|2 Step 2: Install runtime dependencies]]
* [[#Step_3:_Clone_nGate|3 Step 3: Clone nGate]]
* [[#Step_4:_Install_npm_dependencies|4 Step 4: Install npm dependencies]]
* [[#Step_5:_Bootstrap_config.toml|5 Step 5: Bootstrap config.toml]]
* [[#Step_6:_Create_seed.toml|6 Step 6: Create seed.toml (CRITICAL — don't skip)]]
* [[#Step_7:_Configure_ngate.yaml|7 Step 7: Configure ngate.yaml]]
* [[#Step_8:_Dry-run_the_chain|8 Step 8: Dry-run the chain]]
* [[#Step_9:_Merge_sidecar_into_docker-compose.yml|9 Step 9: Merge sidecar into docker-compose.yml]]
* [[#Step_10:_Build_and_start_the_sidecar|10 Step 10: Build and start the sidecar]]
* [[#Step_11:_Watch_a_cycle|11 Step 11: Watch a cycle]]
* [[#Step_12:_Routine_monitoring|12 Step 12: Routine monitoring]]
* [[#Updating_nGate|13 Updating nGate]]
* [[#Known_gotchas|14 Known gotchas]]
* [[#Removing_nGate|15 Removing nGate (back to manual whitelist)]]

== Step 1: SSH to the relay box ==

ssh root@nostr.YOUR-DOMAIN

If you set up a non-root user during stage 1, use that and prefix everything
with <code>sudo</code> as needed.

== Step 2: Install runtime dependencies ==

nGate needs a few things beyond what stage 1 installed. Inside the sidecar
container, all deps are auto-installed (Alpine image bakes Node + jq + curl
+ docker-cli + yq). Outside the container — for dry-runs and manual sync
commands — install on the host:

apt update
apt install -y nodejs npm jq curl

Verify:

for c in bash curl jq sed awk node; do command -v $c >/dev/null && echo "✓ $c" || echo "✗ $c MISSING"; done

All six should print ✓.

== Step 3: Clone nGate ==

The relay lives at <code>/opt/nostr-relay/</code>. Clone nGate next to it so
the bind-mount paths in <code>docker-compose.example.yml</code> work:

cd /opt/nostr-relay
git clone https://github.com/CompleteNoobs/nGate src

That gives you:

/opt/nostr-relay/
├── config.toml ← from stage 1
├── Caddyfile ← from stage 1
├── docker-compose.yml ← from stage 1
├── data/ ← from stage 1 (relay sqlite DB)
├── caddy_data/ ← from stage 1
└── src/ ← NEW (nGate repo)
├── scripts/
├── ngate.yaml.example
├── docker-compose.example.yml
└── ...

For convenience, symlink the scripts dir + copy the YAML template up to
<code>/opt/nostr-relay/</code> (so bind-mount paths are simple):

cd /opt/nostr-relay
ln -s src/scripts scripts
cp src/ngate.yaml.example ngate.yaml

Now <code>scripts/ngate-*.sh</code> work from <code>/opt/nostr-relay/</code>.

'''💡 Tip''': you can also clone nGate anywhere else and adjust the
<code>NGATE_*</code> env-vars in <code>ngate.yaml</code> to point at the
right paths. The clone-into-<code>src/</code>-and-symlink approach is just
the path of least resistance.

== Step 4: Install npm dependencies ==

The Hive ECDSA + Nostr schnorr helpers are Node scripts that need
<code>@hiveio/dhive</code> and <code>nostr-tools</code>:

cd /opt/nostr-relay/src/scripts
npm install

This creates <code>node_modules/</code> in the scripts folder (~35MB).
Gitignored — won't bloat the repo. One-time cost; subsequent
<code>git pull</code> + <code>npm install</code> is incremental.

Verify both deps are present:

ls node_modules/@hiveio/dhive/package.json
ls node_modules/nostr-tools/package.json

Both should exist.

== Step 5: Bootstrap config.toml ==

Your stage-1 <code>config.toml</code> has an <code>[authorization]</code>
section with hand-pasted hex pubkeys. nGate manages a specific block of
this file between BEGIN/END marker comments. Run the bootstrap to wrap your
existing section:

cd /opt/nostr-relay
./scripts/ngate-apply.sh --bootstrap

Output should look like:

ngate-apply: ✓ Bootstrapped — wrapped [authorization] in BEGIN/END markers.
ngate-apply: ngate-apply now manages everything between those markers.
ngate-apply: Operator-edited keys go in: /opt/nostr-relay/seed.toml

Inspect <code>config.toml</code>:

cat /opt/nostr-relay/config.toml

You should see your existing pubkey_whitelist entries, now wrapped:

# === BEGIN NGATE-MANAGED — DO NOT EDIT BY HAND ===
[authorization]
pubkey_whitelist = [
"your_existing_hex_1",
"your_existing_hex_2",
"your_existing_hex_3",
]
# === END NGATE-MANAGED ===

'''⚠ From this point forward, don't hand-edit between those markers.'''
nGate will overwrite that region on every sync. Manual additions go in
<code>seed.toml</code> (next step).

== Step 6: Create seed.toml (CRITICAL — don't skip) ==

'''Why this matters''': nGate's first <code>--apply</code> with
<code>--allow-removals</code> can delete entries that aren't currently
backed by a valid v4call-server post on Hive — including yours, if your
operator key isn't yet announced. Without a seed entry, you can lock
yourself out.

Make a <code>seed.toml</code> at <code>/opt/nostr-relay/seed.toml</code>
listing every hex pubkey that should ALWAYS be allowed, regardless of
discovery state. Most importantly: your own operator key.

nano /opt/nostr-relay/seed.toml

Paste:

# nGate seed list — operator-managed, never auto-removed.
# One hex pubkey per line. Comments allowed.
#
# Critical: include your own operator key here so nGate can't accidentally
# lock you out if your v4call-server post temporarily fails verification.

your_operator_hex_pubkey_here # @noblemage's nostr key

If you've been running stage 1 with 3 manual keys, you might want all 3 as
seeds initially. Worst case is one extra entry in the whitelist; not a
correctness problem.

== Step 7: Configure ngate.yaml ==

Open the YAML config and edit for your relay:

nano /opt/nostr-relay/ngate.yaml

The defaults are sensible. Key fields to customise:

* <code>instance_name</code> — appears in logs. e.g. <code>nostr-hive-book</code>.
* <code>scan_interval_seconds</code> — default 21600 (6 hours). If you
want faster updates and don't mind the Hive RC, drop to 3600 (1 hour).
* <code>gate.account</code> — <code>escrow</code> (default; gates the
operational account that holds caller funds) or <code>hive_account</code>
(gates the announce-signing account).
* <code>gate.min_hp</code> — minimum HP staked. <code>3</code> is a fine
test threshold. Production servers might want 30+.
* <code>gate.min_token_*</code> — leave blank to disable; set to a
Hive-Engine token symbol + amount if you want token-gating.
* <code>max_consecutive_failures</code> — 3 = ~18 hours of absence before
remove. Keep default unless you have a reason.
* <code>restart_command</code> — default <code>docker restart nostr-relay</code>
matches the container_name in your docker-compose.yml. Don't change
unless you renamed the relay container.
* <code>paths.*</code> — only change if you put nGate somewhere other than
<code>/opt/nostr-relay/</code>.

== Step 8: Dry-run the chain ==

Before turning the sidecar loose, run the full pipeline manually in
<code>--dry-run</code> mode (no writes, no restarts):

cd /opt/nostr-relay
./scripts/ngate-scan.sh 2>/dev/null \
| ./scripts/ngate-verify.sh 2>&1 \
| NGATE_MIN_HP=3 ./scripts/ngate-gate.sh 2>&1 \
| ./scripts/ngate-apply.sh

Expected stderr output sequence:

* <code>ngate-scan:</code> ok, N posts
* <code>ngate-verify:</code> OK / REJECT / skip for each candidate
* <code>ngate-gate:</code> OK / REJECT for each verified candidate
* <code>ngate-apply:</code> seed: X loaded, current: Y in whitelist, stdin:
Z passed, summary: add=… keep=… tolerate=… remove=… → DRY RUN, no
files changed.

Read the output. Check that:

* Your own operator key is in the SEED count.
* Your v4call-server post (if you have one) appears as OK in verify and
passes the gate (or fails for an understandable reason).
* The summary "new whitelist size" looks plausible.
* config.toml hasn't been modified (<code>cat config.toml</code> shows the
same content as after bootstrap).

If anything looks off, fix it (re-sign + re-announce, adjust ngate.yaml,
adjust seed.toml) before going live.

== Step 9: Merge sidecar into docker-compose.yml ==

Your stage-1 <code>docker-compose.yml</code> already has the <code>nostr-relay</code>
and <code>caddy</code> services. The nGate sidecar adds a third. Open both
files:

nano /opt/nostr-relay/docker-compose.yml
# In another terminal:
cat /opt/nostr-relay/src/docker-compose.example.yml

Copy the <code>ngate-sync</code> service block from the example into your
real <code>docker-compose.yml</code>. The block looks like:

services:
# ... your existing nostr-relay + caddy services ...

ngate-sync:
build:
context: .
dockerfile: src/scripts/Dockerfile
container_name: ngate-sync
restart: unless-stopped
volumes:
- ./src/scripts:/app/scripts
- ./ngate.yaml:/app/ngate.yaml:ro
- ./seed.toml:/app/seed.toml:ro
- ./config.toml:/app/config.toml
- ./state.json:/app/state.json
- /var/run/docker.sock:/var/run/docker.sock
environment:
- NGATE_YAML=/app/ngate.yaml
depends_on:
- nostr-relay
networks:
- relaynet

(Note: <code>./src/scripts</code> instead of <code>./scripts</code> because
we kept the cloned repo at <code>src/</code> and symlinked. If you did it
differently, adjust the volume paths.)

Make sure to pre-create the state.json so the bind-mount works:

echo '{"last_run":"","last_apply":"","restart_log":[],"candidates":{}}' > /opt/nostr-relay/state.json

'''⚠ Security note''': the sidecar mounts <code>/var/run/docker.sock</code>
so it can <code>docker restart nostr-relay</code>. This gives the sidecar
container effective root on the host. Acceptable on a single-purpose relay
box. NOT acceptable on a multi-tenant machine. If that bothers you, set
<code>restart_command</code> in <code>ngate.yaml</code> to a noop (e.g.
<code>true</code>) and restart the relay manually after each cycle —
configuration writes still work; only the restart is skipped.

== Step 10: Build and start the sidecar ==

cd /opt/nostr-relay
docker compose build ngate-sync
docker compose up -d ngate-sync

First build downloads node:20-alpine + yq + docker-cli (~150MB). Subsequent
builds are fast (cached layers). On startup the sidecar runs
<code>npm install</code> inside the bind-mounted scripts dir if
<code>node_modules</code> isn't present — should be quick if you already
ran step 4.

Check the container's running:

docker compose ps ngate-sync

Should show <code>Up</code>.

== Step 11: Watch a cycle ==

Tail the logs:

docker compose logs -f ngate-sync

The sidecar runs ONE cycle immediately at startup, then sleeps for
<code>scan_interval_seconds</code> between cycles. The first cycle should
show:

[2026-05-13T…] [nostr-hive-book] starting ngate-sync instance=… interval=21600s …
[2026-05-13T…] [nostr-hive-book] ─── cycle starting ───
ngate-scan: trying https://api.hive.blog …
ngate-scan: ok, N posts
ngate-scan: scan complete
ngate-verify: OK @cnoobs/call.completenoobs.com — Hive sig + Nostr attestation valid …
ngate-verify: OK @v4call/v4call.com — Hive sig + Nostr attestation valid …
ngate-verify: OK @hive-book/hive-book.com — Hive sig + Nostr attestation valid …
ngate-gate: config: account=escrow mode=or hp_enabled=1 (>=3, delegated=false) …
ngate-gate: OK @cnoobs/… — passed via hp hp=…
ngate-gate: complete — total=3 passed=3 rejected=0 errors=0
ngate-apply: seed: 1 pubkey(s) loaded from /app/seed.toml
ngate-apply: current: 3 pubkey(s) in /app/config.toml whitelist
ngate-apply: stdin: 3 candidate(s) passed gate this run
ngate-apply: summary: add=… keep=… tolerate=0 remove=0 seed=1 → new whitelist size = …
ngate-apply: ✓ wrote new whitelist to /app/config.toml
ngate-apply: restarting relay: docker restart nostr-relay
ngate-apply: ✓ restart succeeded
[2026-05-13T…] [nostr-hive-book] ─── cycle complete (apply ok) ───
[2026-05-13T…] [nostr-hive-book] sleeping 21600s until next cycle

After this, your <code>config.toml</code>'s nGate-managed block should
reflect the discovered+gated set.

Verify the relay still works:

docker compose ps nostr-relay # Up
# From your laptop:
nak req -k 1 -a YOUR_HEX wss://nostr.YOUR-DOMAIN

If it returns events, the restart worked cleanly.

== Step 12: Routine monitoring ==

;'''Status snapshot'''
:From inside the sidecar:
: <code>docker compose exec ngate-sync /app/scripts/ngate-status.sh</code>
:Or from the host (env-vars on the command):
:
: NGATE_YAML=/opt/nostr-relay/ngate.yaml \
: NGATE_STATE_PATH=/opt/nostr-relay/state.json \
: NGATE_CONFIG_PATH=/opt/nostr-relay/config.toml \
: NGATE_SEED_PATH=/opt/nostr-relay/seed.toml \
: /opt/nostr-relay/scripts/ngate-status.sh

;'''Logs'''
:* <code>docker compose logs -f ngate-sync</code> — live stream
:* <code>tail -F /opt/nostr-relay/ngate-sync.log</code> — bind-mounted host file

;'''Manual sync'''
:If you want a fresh cycle right now (don't wait 6 hours):
: <code>docker compose exec ngate-sync /app/scripts/ngate-sync.sh --once</code>
:Or restart the sidecar (runs one cycle on startup):
: <code>docker compose restart ngate-sync</code>

;'''Inspect state.json'''
:Shows per-key first-seen, last-seen, consecutive_misses, source
:(discovery|seed|removed):
: <code>jq . /opt/nostr-relay/state.json</code>

== Updating nGate ==

When the repo updates:

cd /opt/nostr-relay/src
git pull
cd scripts && npm install # in case dep versions changed
cd /opt/nostr-relay
docker compose build ngate-sync # only needed if Dockerfile changed
docker compose restart ngate-sync

The scripts dir is bind-mounted, so script-only changes take effect on next
sync without rebuild. Restart picks them up immediately.

== Known gotchas ==

;'''"Keychain not detected" in server-announce''' (browser-side, not nGate)
:Some browsers don't expose <code>window.hive_keychain</code> even with the
:extension installed (iOS Safari, Brave on iOS, etc.). server-announce.html
:has a posting-key paste fallback that uses dhive to broadcast directly —
:scroll past the Keychain button to the "POSTING KEY PASTE" section. Key
:never leaves your browser.

;'''nGate-verify rejects with "no nostr_attestation in well-known OR post"'''
:Your v4call-server post is pre-attestation, OR the well-known doesn't have
:the <code>nostr_attestation</code> field, OR the post body doesn't have a
:<code>NOSTR-ATTESTATION:</code> base64 line. Re-sign in
:<code>server-sign.html</code> (Option B canonical) and re-announce. The
:full chain produces both the well-known field AND the post-body line in
:one signed event.

;'''nGate-verify rejects with "Hive signature DID NOT verify"'''
:Most common cause: signature was computed under a DIFFERENT canonical
:payload shape than what nGate-verify reconstructs. Re-sign with the
:current server-sign.html (which produces the Option B / SHORT canonical
:that nGate-verify and v4call's existing federation code both expect).

;'''nGate-verify rejects with "attestation v4call_hive_account tag (X) ≠ post's HIVE-ACCOUNT (Y)"'''
:You signed the attestation with one Hive account name (e.g.
:<code>hive-book</code>) but the Hive post declares a different one (e.g.
:<code>hive-book.com</code>). Re-sign with consistent values across the
:whole flow (server-sign → server-announce → Hive post).

;'''Sidecar can't restart relay ("permission denied" on docker.sock)'''
:Less common, but if the relay box has docker access locked down: either
:loosen perms on <code>/var/run/docker.sock</code> (default world-writable
:on most distros) OR change <code>restart_command</code> in ngate.yaml to
:a noop and restart the relay manually after each sync.

;'''Sidecar in a restart loop'''
:Probably an invalid <code>ngate.yaml</code> or missing
:<code>node_modules</code>. Check:
: <code>docker compose logs --tail=50 ngate-sync</code>
:The startup log shows YAML parse errors clearly. If
:<code>node_modules</code> is missing the sidecar will install it on first
:start; subsequent runs are fast.

;'''"Restart cap hit" in logs'''
:nGate refuses to restart the relay more than
:<code>max_restarts_per_day</code> times in 24h. If you see this
:repeatedly, something upstream is causing the whitelist to flap.
:Investigate state.json and check whether candidates are missing-then-back
:repeatedly (suggests Hive RPC flakiness or a v4call-server post
:disappearing temporarily).

;'''"Sanity bound triggered" in logs'''
:nGate refused to apply because the result would have removed every
:non-seed entry. Triggered when upstream had errors AND
:<code>--allow-removals</code> was somehow set. With the sidecar's
:PIPESTATUS-aware logic, this shouldn't happen in practice; if it does,
:check upstream phase exit codes.

== Removing nGate (back to manual whitelist) ==

If you want to disable nGate and go back to hand-editing
<code>config.toml</code>:

cd /opt/nostr-relay
docker compose down ngate-sync
docker compose rm -f ngate-sync

Then manually edit <code>config.toml</code>:

nano /opt/nostr-relay/config.toml

Either:

* Delete the BEGIN/END marker comments (keep the
<code>[authorization]</code> section between them as-is), OR
* Replace the entire managed block with a hand-curated whitelist.

Restart the relay to pick up the new config:

docker compose restart nostr-relay

The relay reads <code>config.toml</code> on startup regardless of markers.
nGate's markers are JUST for nGate's internal "what to manage" logic; the
relay itself ignores them as TOML comments.

== When you're done ==

After 24 hours of clean runs, nGate has handled at least one normal cycle
(scan + verify + gate + maybe-apply). At that point you can:

* Stake some HIVE on your test operator to confirm a transition (off-gate
→ passing the gate after stake).
* Publish a v4call-server post for a new operator and watch it get picked
up on the next cycle.
* Deploy nGate to your second relay box (nostr.v4call.com) with a
staggered scan time (set <code>scan_interval_seconds</code> the same but
schedule the startup at a different time of day for faster
federation-wide pickup).

For the next phase of work (stage 3.6 refinements + stage 4 strfry
migration), see [[STATUS.md]] in the nGate repo.

V4call-server-data-flow

2026-05-26T00:36:05Z

AwesomO: Created page with "{{:LICENCE_HEADER_MIT}} = v4call Server Data Flow — Sign, Announce, Verify, Gate — A Noob Reference = From CompleteNoobs A clear-cut reference for which value goes in which field across <code>server-sign.html</code>, <code>server-announce.html</code>, the <code>/.well-known/v4call-server.json</code> file, the Hive announce post, and the four nGate scripts. Use this when you're not 100% sure what to type into a form, or when nGate-verify gives you an error and you..."

{{:LICENCE_HEADER_MIT}}

= v4call Server Data Flow — Sign, Announce, Verify, Gate — A Noob Reference =

From CompleteNoobs

A clear-cut reference for which value goes in which field across <code>server-sign.html</code>, <code>server-announce.html</code>, the <code>/.well-known/v4call-server.json</code> file, the Hive announce post, and the four nGate scripts. Use this when you're not 100% sure what to type into a form, or when nGate-verify gives you an error and you don't know which value caused it.

This doc complements [[Nostr_Relay_With_a_3-Key_Whitelist|stage 1]], [[Nostr_Hands-On|stage 2]], and [[NGate_—_Auto-Whitelist_a_Nostr_Relay|stage 3]] — it's not a phase, it's a "wait, I'm confused, what's what?" reference you can flip to any time.

== The single biggest source of confusion: '''3 different "accounts"''' ==

These are three '''separate''' things. They might happen to share names. They are not the same.

{| class="wikitable"
! Thing !! Example !! What it is !! Where it lives
|-
| '''HIVE ACCOUNT''' || <code>cnoobs</code> || A Hive blockchain account. Has a posting key, an active key, and an owner key. Signs the announce post. || On Hive (chain). Resolved by name lookup.
|-
| '''ESCROW ACCOUNT''' || <code>cnoobs-escrow</code> || ANOTHER Hive blockchain account, used by v4call-server to hold caller funds during paid calls. Its active key must be in <code>V4CALL_ESCROW_KEY</code> on the v4call server. Default nGate gate target. || On Hive (chain). Different from the HIVE ACCOUNT above. Could be the same account, but usually isn't (operational separation).
|-
| '''DOMAIN''' || <code>call.completenoobs.com</code> || An '''internet hostname'''. Has DNS records. Hosts your v4call server's HTTPS endpoint AND the <code>.well-known/v4call-server.json</code> file. || In DNS. Has nothing to do with Hive — domains are not blockchain accounts.
|}

'''Common confusion patterns''' from real test sessions:
* Putting <code>call.completenoobs.com</code> (a domain) into the HIVE ACCOUNT field. Hive accounts don't have dots-and-tlds; <code>call.completenoobs.com</code> is the DOMAIN field.
* Putting <code>hive-book.com</code> (the domain) into the HIVE ACCOUNT field, signing it, and ending up with a well-known that says <code>"hive_account": "hive-book.com"</code>. nGate-verify catches it and rejects.
* Staking HP on <code>v4call</code> (the announcing HIVE ACCOUNT) when the gate is checking <code>v4call-escrow</code> (the escrow). Staking on the wrong account ≠ staking.

== The data flow (what goes where) ==

┌──────────────────────────────────────────────────────────────────────────┐
│ YOU (operator) │
│ Decide your 3 accounts + your domain first │
└────────────────────────────┬─────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────────────┐
│ Step 1 — server-sign.html │
│ │
│ You fill in the IDENTITY card and SERVER CONFIG card and (optionally) │
│ the NOSTR card. Then click "Sign with Hive Keychain". │
│ │
│ KEYCHAIN signs a "|"-joined canonical string with the HIVE ACCOUNT's │
│ posting key. Output is a single signed JSON file. │
└────────────────────────────┬─────────────────────────────────────────────┘
│
│ Download JSON →
│ deploy to server's filesystem at
│ /public/.well-known/v4call-server.json
│ Rebuild + restart the v4call container.
▼
┌──────────────────────────────────────────────────────────────────────────┐
│ https://YOUR-DOMAIN/.well-known/v4call-server.json │
│ │
│ Anyone in the world can fetch this. It's the cryptographic ground │
│ truth: "This Hive account vouches for this domain." │
└────────────────────────────┬─────────────────────────────────────────────┘
│
│ "Next step →" link in server-sign.html
│ opens server-announce.html with all the
│ same fields prefilled via querystring
▼
┌──────────────────────────────────────────────────────────────────────────┐
│ Step 2 — server-announce.html │
│ │
│ Fields are auto-filled from server-sign. Verify they match. Click │
│ "Post to Hive". KEYCHAIN signs a Hive post broadcast. │
└────────────────────────────┬─────────────────────────────────────────────┘
│
│ Hive consensus stores the post forever.
│ Tagged "v4call-server".
▼
┌──────────────────────────────────────────────────────────────────────────┐
│ HIVE BLOCKCHAIN — the public directory of v4call servers │
│ │
│ Other nGate operators query this for new candidates. │
└────────────────────────────┬─────────────────────────────────────────────┘
│
│ ngate-scan.sh queries Hive
▼
┌──────────────────────────────────────────────────────────────────────────┐
│ ngate-scan.sh — Phase 3.1 │
│ │
│ Reads each post's V4CALL-SERVER-V1 block, emits NDJSON candidate. │
└────────────────────────────┬─────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────────────┐
│ ngate-verify.sh — Phase 3.2 │
│ │
│ For each candidate, fetches the well-known JSON and runs FIVE checks: │
│ ───────────────────────────────────────────────────────────────────── │
│ │
│ ① Reachable: HTTPS GET of verify_url returns 200 + parses as JSON │
│ ② Schema: well-known has claim, signature, hive_account, nonce │
│ ③ HIVE-ACCOUNT cross-check: │
│ well-known.hive_account == post's HIVE-ACCOUNT field │
│ ④ NOSTR-HEX cross-check (defense in depth, optional): │
│ well-known.nostr_hex == post's NOSTR-PUBKEY-HEX (if both present) │
│ ⑤ SIGNATURE cross-check: │
│ fetches HIVE-ACCOUNT's posting pubkey from Hive, │
│ reproduces canonical "|"-joined payload from well-known fields, │
│ verifies signature using @hiveio/dhive │
└────────────────────────────┬─────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────────────┐
│ ngate-gate.sh — Phase 3.3 │
│ │
│ For each verified candidate, picks the gate target: │
│ • NGATE_GATE_ACCOUNT=escrow (default) → checks ESCROW account │
│ • NGATE_GATE_ACCOUNT=hive_account → checks HIVE-ACCOUNT │
│ │
│ Fetches HP from Hive, fetches token balance from Hive-Engine, │
│ applies thresholds and OR/AND mode, emits passing candidates. │
└──────────────────────────────────────────────────────────────────────────┘

== server-sign.html — field-by-field reference ==

What to put in each field, what value type, where it ends up. Every field is in BOTH the signed JSON AND (later, by querystring chain) the announce post.

{| class="wikitable"
! Field !! Type !! Example !! ⚠ Common mistakes
|-
| HIVE ACCOUNT (the one that signs) || Hive account name || <code>cnoobs</code> || ❌ Putting the domain (<code>cnoobs.com</code>). ❌ Putting an email. ❌ Putting a Nostr npub.
|-
| DOMAIN || Hostname (no scheme, no path) || <code>call.completenoobs.com</code> || ❌ Adding <code>https://</code> or trailing slash. ❌ Putting a Hive account name.
|-
| ESCROW ACCOUNT || Hive account name || <code>cnoobs-escrow</code> || ❌ Same as HIVE ACCOUNT (allowed but not recommended — operational separation matters). ❌ Putting an account whose active key isn't on the v4call server.
|-
| FEE ACCOUNT || Hive account name || <code>cnoobs</code> || Often same as HIVE ACCOUNT. ❌ A different chain's account.
|-
| FEDERATION-WS || WebSocket URL || <code>wss://call.completenoobs.com/federation</code> || ❌ Missing <code>wss://</code>. ❌ Wrong domain. ❌ Forgetting <code>/federation</code>.
|-
| NOSTR PUBKEY (npub) || Bech32 string starting <code>npub1</code> || <code>npub1cxgaen…q57qw3d</code> || ❌ Pasting an nsec (the secret key — never paste secrets into form fields you didn't write yourself). ❌ Pasting hex into the npub field (use the auto-sync — it'll auto-fill).
|-
| NOSTR PUBKEY (hex) || 64-char lowercase hex || <code>c191dccd…1ba12c</code> || ❌ Uppercase. ❌ Wrong length. (Auto-fills if you typed a valid npub above.)
|-
| NOSTR RELAY 1–5 || WebSocket URLs || <code>wss://nostr.v4call.com</code> || ❌ Missing <code>wss://</code>. (Slots 3–5 left blank are silently skipped.)
|-
| ISSUED || Auto-filled || timestamp at sign time || (Don't touch — auto-filled by server-sign.)
|-
| NONCE || Auto-filled || random hex || (Don't touch — auto-filled.)
|-
| EXPIRES || Optional date || <code>2027-01-01</code> || (Most operators leave blank. Set only if you have a specific rotation schedule.)
|}

After signing, you '''download''' the signed JSON and '''deploy''' it to:
* The v4call repo's <code>public/.well-known/v4call-server.json</code> (overwriting the placeholder).
* Rebuild + restart: <code>docker compose down && docker compose build --no-cache && docker compose up -d</code>.
* Test reachable: <code>curl https://YOUR-DOMAIN/.well-known/v4call-server.json</code> should return your file.

== server-announce.html — field-by-field reference ==

server-announce auto-fills from server-sign's "Next step →" link. Verify the prefilled fields match what you signed. Don't post mismatched data.

{| class="wikitable"
! Field !! Same as server-sign? !! Why it's here too
|-
| HIVE ACCOUNT (poster) || YES — must match || Hive consensus needs to know who's authoring this post.
|-
| DOMAIN || YES || nGate-scan reads this from the post; ngate-verify uses it to fetch the well-known.
|-
| ESCROW ACCOUNT || YES || Default gate target. Visible in the directory entry.
|-
| FEE ACCOUNT || YES || Visible in the directory entry. Informational.
|-
| FEDERATION-WS || YES || How peer servers connect for federation.
|-
| VERIFY URL (auto) || Auto-computed from DOMAIN || <code>https://DOMAIN/.well-known/v4call-server.json</code>.
|-
| SOFTWARE / PROTOCOL || Optional || Forks may put their own software name here.
|-
| NOSTR fields || YES (auto-filled from sign) || Optional. Lets nGate-scan pick up the Nostr key claim.
|-
| POST TAGS || <code>v4call-server, v4call, hive</code> || First tag MUST be <code>v4call-server</code> — that's what nGate-scan searches for.
|-
| INTRO PARAGRAPH || Optional human readable || Just the prose at the top of the post. Doesn't affect any field parsing.
|}

After clicking "Post to Hive" + Keychain confirm, the post is live on Hive. '''The post is permanent''' — Hive doesn't allow deletion. If you made a typo, you can publish a NEW post with the corrected fields; nGate-scan picks up the most recent one for each (account, domain) pair.

== What ends up in the signed JSON ==

The JSON file at <code>/.well-known/v4call-server.json</code>. Public, fetchable from anywhere, signed by your HIVE ACCOUNT's posting key.

{
"claim": "v4call-server-ownership", ← fixed string
"domain": "call.completenoobs.com", ← from DOMAIN
"hive_account": "cnoobs", ← from HIVE ACCOUNT
"escrow": "cnoobs-escrow", ← from ESCROW ACCOUNT
"fee_account": "cnoobs", ← from FEE ACCOUNT
"federation_ws": "wss://call.completenoobs.com/federation",
"issued": "2026-05-08T11:18:00Z", ← auto
"expires": "", ← optional
"nonce": "abc123def456", ← auto
"key_type": "posting", ← fixed
"signature": "1f4a3b…", ← Hive ECDSA signature

// Optional Nostr fields (only present if you filled the NOSTR card):
"nostr_npub": "npub1cxgaen…q57qw3d",
"nostr_hex": "c191dccd…1ba12c",
"nostr_relays": ["wss://nostr.v4call.com", "wss://nostr.hive-book.com"]
}

The signature is over a single canonical string built from these fields in a fixed order — server-sign.html computes it; nGate-verify reproduces it. If a single character of any signed field is different between the well-known and what was signed, verification fails.

== What ends up in the Hive post body ==

The announce post body has a markdown-code-block like this (4 leading spaces per line — that's how Hive renders the block):

[V4CALL-SERVER-V1]
DOMAIN: call.completenoobs.com ← from DOMAIN field
HIVE-ACCOUNT: cnoobs ← from HIVE ACCOUNT field
ESCROW: cnoobs-escrow ← from ESCROW ACCOUNT field
FEE-ACCOUNT: cnoobs ← from FEE ACCOUNT field
FEDERATION-WS: wss://call.completenoobs.com/federation
VERIFY-URL: https://call.completenoobs.com/.well-known/v4call-server.json
SOFTWARE: v4call
PROTOCOL: 0.3
NOSTR-PUBKEY: npub1cxgaen…q57qw3d ← from NOSTR NPUB field
NOSTR-PUBKEY-HEX: c191dccd…1ba12c ← from NOSTR HEX field
NOSTR-RELAYS: wss://nostr.v4call.com, wss://nostr.hive-book.com
DECLARED: 2026-05-08T11:18:30Z ← timestamp at post time
[/V4CALL-SERVER-V1]

ngate-scan reads exactly this block. Field names are matched case-sensitively after stripping leading whitespace. Lines that don't match a known field are ignored.

== What nGate-verify cross-checks (and what each rejection means) ==

In order — verify stops at the first failure for each candidate.

{| class="wikitable"
! Check !! Failure looks like !! Real-world cause !! Fix
|-
| Reachable + valid JSON || <code>could not fetch verify_url</code> || Domain not deployed yet, DNS not propagated, container not rebuilt after dropping in the new well-known file || Deploy the JSON, rebuild + restart container, test with curl
|-
| Schema fields exist || <code>well-known missing required fields</code> || Old or corrupted JSON file || Re-sign via server-sign.html, redeploy
|-
| Claim string == "v4call-server-ownership" || <code>wrong claim string</code> || Someone deployed a non-v4call signed JSON || (Won't happen if you used server-sign.html)
|-
| HIVE ACCOUNT match || <code>well-known hive_account (X) ≠ post's HIVE-ACCOUNT (Y)</code> || '''You typed a different value in the HIVE ACCOUNT field on server-sign vs. on server-announce''' (or you re-signed and forgot to re-announce) || Re-sign with the correct HIVE ACCOUNT, redeploy, re-announce
|-
| Nostr hex match (if both have it) || <code>well-known nostr_hex differs from post</code> || You signed with one Nostr key, then re-announced with a different one (typo or rotation) || Re-sign with the correct NOSTR HEX, redeploy, re-announce
|-
| Expires not in the past || <code>well-known expired at X</code> || You set an EXPIRES date that has already passed || Re-sign with a fresh ISSUED timestamp (and either no expiry or a future one)
|-
| Within-scan hex collision || <code>FORGERY-FLAG hex=… claimed by both @A and @B — both will be REJECTED</code> || Two operators announcing with the same Nostr hex (one is forged) || Both REJECTED on purpose. Only one operator should hold each Nostr keypair. Re-keying anyone caught in this is mandatory
|-
| Signature valid || <code>signature DID NOT verify</code> || The well-known was tampered with after signing, OR you signed with a different account's posting key by mistake || Re-sign via server-sign.html (fresh issued + nonce), redeploy
|}

== What nGate-gate looks at (and which account matters) ==

By default, nGate-gate checks the '''ESCROW account''', not the announcing HIVE ACCOUNT.

;Why escrow?
:Escrow is the operational account — it actually moves money during paid calls. Gating on its HP/RC enforces "this server can actually operate," not just "the operator owns a Hive account."

;When you'd switch to <code>NGATE_GATE_ACCOUNT=hive_account</code>:
* Testing with a token gate where the HIVE-ACCOUNT holds the test tokens but the escrow doesn't (e.g. CNOOBS).
* Specific governance use cases where the announcer's reputation matters more than the operational account's solvency.

;'''Worked example from a real test session''' (yours):
* You staked 3 HP on <code>v4call</code> (the HIVE-ACCOUNT).
* nGate-gate's default = check ESCROW = <code>v4call-escrow</code>.
* <code>v4call-escrow</code> still has 0 HP.
* Result: rejected with <code>gate→@v4call-escrow … hp=0.000/3=false</code>.
* Fix A (no Hive transactions): <code>NGATE_GATE_ACCOUNT=hive_account NGATE_MIN_HP=3 ./ngate-gate.sh</code> → checks <code>v4call</code>'s HP, passes.
* Fix B (matches default architecture): Power Up 3 HIVE on <code>v4call-escrow</code> directly.

== Common mistakes — based on real test sessions ==

;'''Mistake #1: Putting the domain in HIVE ACCOUNT'''
:Result: well-known has <code>"hive_account": "your-domain.com"</code>. nGate-verify rejects with <code>well-known hive_account (your-domain.com) ≠ post's HIVE-ACCOUNT (your-account)</code>.
:Fix: server-sign.html with HIVE ACCOUNT = <code>your-account</code> (just the Hive name, no .com).

;'''Mistake #2: Staking HP on the wrong account'''
:Result: gate fails for an operator you'd expect to pass.
:Fix: read the <code>(gate→@account)</code> in the rejection — it tells you which account was checked. Stake there, OR change <code>NGATE_GATE_ACCOUNT</code>.

;'''Mistake #3: Not re-announcing after re-signing'''
:Result: well-known has updated fields, but the post on Hive still has the old ones. nGate-verify cross-checks see a mismatch.
:Fix: '''always do server-sign + server-announce together as a pair'''. The "Next step →" button on server-sign goes to server-announce with prefilled fields exactly to keep these in sync.

;'''Mistake #4: Pre-Nostr announce posts still in the scan window'''
:Symptom: <code>skip @user/domain — no nostr_pubkey_hex (pre-Nostr announce; not an error)</code>.
:Cause: you announced before nostr fields were added; the old post still appears in Hive's recent-20 query.
:Fix: nothing required. Each operator only needs ONE current announce; older posts age out. If you want the relay to stop seeing them sooner, just publish a fresh announce — your latest takes precedence in Hive's recent-by-created order.

;'''Mistake #5: Signing without rebuilding the container'''
:Result: deployed the new well-known JSON to disk but the v4call Docker container still serves the old one (Docker images bake in static files at build time).
:Fix: <code>docker compose down && docker compose build --no-cache && docker compose up -d</code> after every well-known change.

;'''Mistake #6: Posting before deploying the well-known'''
:Result: announce post is live on Hive; nGate-scan picks it up; nGate-verify tries to fetch the well-known and gets a 404 → rejection.
:Fix: deploy + rebuild + verify with curl FIRST, then announce. Or fix the well-known and wait for the next scan cycle — eventual consistency.

;'''Mistake #7: Staking "exactly N HIVE" but the gate at <code>NGATE_MIN_HP=N</code> still fails'''
:Symptom: <code>REJECT … gate failed hp=2.999/3=false</code> (or some near-round-number mismatch).
:Cause: HIVE → VESTS → HP round-trip uses 6-decimal vesting math. Staking exactly 3 HIVE can land at 2.999something HP, not exactly 3.000. The gate's comparison is correct (<code>>=</code> not <code>></code>), but the input itself is just slightly under the threshold.
:Fix A: Stake slightly above the threshold (e.g. 4 HIVE for a <code>NGATE_MIN_HP=3</code> gate).
:Fix B: Set the threshold slightly below the stake (e.g. <code>NGATE_MIN_HP=2.5</code>).
:Both work. The first feels "rounder" to the operator; the second uses fewer HIVE. Either is fine.

;'''Mistake #8 — a transient Hive RPC outage shows up as an ERROR line'''
:Symptom: <code>ngate-gate: ERROR … HP fetch failed (transient Hive RPC); not passing</code> on one or more candidates, with the run summary showing <code>errors=1</code>+.
:Cause: Hive node didn't respond before the script's timeout. Not your fault; not a config bug.
:What happens: that candidate is treated as "not passing" for THIS run, so it doesn't get added/refreshed. The script exits with code 2 (partial fetch errors). Phase 3.4 reads this exit code and refuses to REMOVE any existing entries from the whitelist — so a single bad cycle can't kick legitimate operators off your relay.
:Fix: nothing required. Re-run when Hive is healthy. The "ADD-only on partial failure" rule is the design's safety net; this output is what it looks like working.

== Clean-redo checklist ==

If you're re-doing an operator's announce and want to be sure each step is correct, follow this exact order. Tick them off mentally as you go.

# '''☐ Confirm your three accounts and one domain''' on a piece of paper:
#: HIVE ACCOUNT = ___________________ (e.g. <code>cnoobs</code>, no <code>.com</code>)
#: ESCROW ACCT = ___________________ (e.g. <code>cnoobs-escrow</code>, no <code>.com</code>)
#: FEE ACCT = ___________________ (often same as HIVE ACCOUNT)
#: DOMAIN = ___________________ (e.g. <code>call.completenoobs.com</code>, no scheme/path)
#: NOSTR NPUB = ___________________ (from <code>nostr-gen.html</code>)
# '''☐ Open server-sign.html'''. Fill the IDENTITY card, SERVER CONFIG card, and (optionally) NOSTR card with the values above. Verify each line of the form against your paper.
# '''☐ Click "Sign with Hive Keychain"'''. Confirm in Keychain.
# '''☐ Download the signed JSON'''. Open it in a text editor. Eyeball the top fields — they should match your paper.
# '''☐ Deploy the JSON to your v4call repo''' at <code>public/.well-known/v4call-server.json</code> (overwriting whatever was there).
# '''☐ Rebuild + restart''' your v4call container: <code>docker compose down && docker compose build --no-cache && docker compose up -d</code>.
# '''☐ Test reachability''': <code>curl https://YOUR-DOMAIN/.well-known/v4call-server.json</code> on your laptop. Should return the same JSON you just deployed.
# '''☐ Click the "Next step →" link''' on server-sign.html (it auto-opens server-announce.html with all fields prefilled from the querystring). Verify the prefilled fields match your paper.
# '''☐ Click "Post to Hive"'''. Confirm in Keychain. Wait for the success banner.
# '''☐ Verify end-to-end''': from your laptop, run <code>./nGate/scripts/ngate-scan.sh | ./nGate/scripts/ngate-verify.sh</code>. Look for <code>OK @your-account/your-domain — signature valid</code>.
# '''☐ Test the gate''': <code>./ngate-scan.sh | ./ngate-verify.sh | NGATE_MIN_HP=3 ./ngate-gate.sh</code>. Read the <code>(gate→@account)</code> on each rejection — that's the account whose HP it's checking. Stake there OR pick a different gate target.

If anything fails, the rejection message tells you which check failed — see "What nGate-verify cross-checks" or "What nGate-gate looks at" above for the recipe.

== Quick reference card ==

Print this. Tape it next to your monitor while doing operator work.

╔══════════════════════════════════════════════════════════════════════╗
║ v4call ANNOUNCE QUICK REFERENCE ║
╠══════════════════════════════════════════════════════════════════════╣
║ ║
║ 3 ACCOUNTS + 1 DOMAIN — these are NOT the same thing: ║
║ ║
║ HIVE ACCOUNT → signs the announce (e.g. cnoobs) ║
║ ESCROW ACCT → holds funds, gate target (e.g. cnoobs-escrow) ║
║ FEE ACCT → receives platform fees (often = HIVE ACCT) ║
║ DOMAIN → internet hostname (call.completenoobs.com)║
║ ║
║ ALWAYS DO TOGETHER (one breaks if you skip the other): ║
║ ║
║ server-sign.html ─→ deploy + rebuild ─→ server-announce.html ║
║ ║
║ STAKING FOR THE GATE — stake on the right account: ║
║ ║
║ NGATE_GATE_ACCOUNT=escrow (default) → stake on ESCROW ║
║ NGATE_GATE_ACCOUNT=hive_account → stake on HIVE ACCT ║
║ ║
║ WHEN VERIFY FAILS — read the rejection reason: ║
║ ║
║ "well-known hive_account (X) ≠ post's HIVE-ACCOUNT (Y)" ║
║ → typo on one of the two; re-sign with correct value ║
║ ║
║ "signature DID NOT verify" ║
║ → well-known tampered with OR signed by wrong account ║
║ → re-sign cleanly ║
║ ║
║ "could not fetch verify_url" ║
║ → JSON not deployed OR container not rebuilt ║
║ → docker compose down/build/up, curl-test from laptop ║
║ ║
║ "skip … no nostr_pubkey_hex" ║
║ → pre-Nostr announce, harmless, ignore ║
║ ║
║ DEFAULT GATE TARGET: ║
║ ║
║ Escrow account. (Operational solvency check.) ║
║ To check announcing account instead: ║
║ NGATE_GATE_ACCOUNT=hive_account ║
║ ║
╚══════════════════════════════════════════════════════════════════════╝

NGate

2026-05-08T18:00:37Z

AwesomO: Created page with "* nGate-dev Stage 1: https://www.completenoobs.com/noobs/Nostr-relay-with-whitelist Stage 2: https://www.completenoobs.com/noobs/Nostr-handson"

* nGate-dev

Stage 1: https://www.completenoobs.com/noobs/Nostr-relay-with-whitelist

Stage 2: https://www.completenoobs.com/noobs/Nostr-handson

Nostr-handson

2026-05-08T17:59:50Z

AwesomO: Created page with "{{:LICENCE_HEADER_MIT}} = Nostr Hands-On — Send Your First Notes and DMs Through Your Own Relays = From CompleteNoobs Stage 2 of the Nostr learning path. Stage 1 (nostr-relay-with-whitelist) got you ''two private write-whitelisted relays'' running. This stage gets you actually ''using'' Nostr — sending public notes, sending encrypted DMs, subscribing to events, watching the raw pro..."

{{:LICENCE_HEADER_MIT}}

= Nostr Hands-On — Send Your First Notes and DMs Through Your Own Relays =

From CompleteNoobs

Stage 2 of the Nostr learning path. Stage 1 ([[Nostr_Relay_With_a_3-Key_Whitelist_—_Two_Servers_on_Ubuntu_24.04_with_Docker|nostr-relay-with-whitelist]]) got you ''two private write-whitelisted relays'' running. This stage gets you actually ''using'' Nostr — sending public notes, sending encrypted DMs, subscribing to events, watching the raw protocol — using a single static HTML page that you can read, modify, and break.

We deliberately skip Primal / nostrudel / Damus etc. for stage 2. Real clients hide the protocol behind a UX, and the noob ends up "using Nostr" without ever seeing what Nostr ''is''. Instead, you'll use <code>nostr-handson.html</code> from this folder — a one-file, no-install learning tool. After 30 minutes with it, you'll understand more about Nostr than most people who've used a client for months.

'''End result of stage 2''': you can publish a signed Nostr event from your laptop, see it land on your private relay, query it back over the wire, send an encrypted DM between two of your whitelisted identities, and read every JSON message that flowed through the browser's developer console.

== nostr-handson.html code ==
<div class="toccolours mw-collapsible mw-collapsed">
<code>nostr-handson.html</code>
<div class="mw-collapsible-content">
<pre>
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Nostr Hands-On — completenoobs</title>
<meta name="viewport" content="width=device-width, initial-scale=1">
<style>
:root {
--bg: #0d0d0d;
--surface: #1a1a1a;
--surface2: #252525;
--accent: #f5a623;
--green: #5cb85c;
--blue: #5bc0de;
--purple: #9b59b6;
--red: #d9534f;
--text: #e0e0e0;
--subtext: #b0b0b0;
--muted: #707070;
--border: #333;
}
* { box-sizing: border-box; }
body {
background: var(--bg);
color: var(--text);
font-family: 'IBM Plex Sans', system-ui, sans-serif;
margin: 0;
padding: 20px;
max-width: 1100px;
margin-left: auto; margin-right: auto;
}
header {
border-bottom: 2px solid var(--accent);
padding-bottom: 10px;
margin-bottom: 20px;
}
header h1 { margin: 0; color: var(--accent); font-family: 'IBM Plex Mono', monospace; }
header p { color: var(--subtext); margin: 6px 0 0; font-size: 0.9rem; }

section {
background: var(--surface);
border: 1px solid var(--border);
border-radius: 8px;
padding: 14px 16px;
margin-bottom: 14px;
}
section h2 {
margin: 0 0 8px;
color: var(--accent);
font-size: 0.95rem;
font-family: 'IBM Plex Mono', monospace;
}
.help {
color: var(--subtext);
font-size: 0.85rem;
margin-bottom: 10px;
line-height: 1.4;
}

input, textarea, button, select {
background: var(--surface2);
color: var(--text);
border: 1px solid var(--border);
border-radius: 4px;
padding: 6px 10px;
font-family: 'IBM Plex Mono', monospace;
font-size: 0.85rem;
}
input:focus, textarea:focus { border-color: var(--accent); outline: none; }
button { cursor: pointer; }
button:hover { border-color: var(--accent); }
button.primary { background: var(--accent); color: #000; border-color: var(--accent); font-weight: 600; }
button.primary:hover { filter: brightness(1.1); }
button.danger { color: var(--red); border-color: var(--red); }
button:disabled { opacity: 0.4; cursor: not-allowed; }

.row { display: flex; gap: 8px; align-items: center; margin-bottom: 8px; flex-wrap: wrap; }
.row > input { flex: 1; min-width: 200px; }

.warn {
background: rgba(217,83,79,0.08);
border: 1px solid var(--red);
color: var(--red);
padding: 8px 12px;
border-radius: 4px;
font-size: 0.82rem;
margin-bottom: 10px;
line-height: 1.4;
}
.tip {
background: rgba(245,166,35,0.07);
border: 1px solid rgba(245,166,35,0.3);
color: var(--subtext);
padding: 6px 10px;
border-radius: 4px;
font-size: 0.78rem;
margin-top: 8px;
line-height: 1.4;
}

.tab-buttons { display: flex; gap: 4px; margin-bottom: 10px; }
.tab-buttons button {
border-bottom: 2px solid transparent;
border-radius: 4px 4px 0 0;
}
.tab-buttons button.active {
border-bottom-color: var(--accent);
color: var(--accent);
}
.tab-pane { display: none; }
.tab-pane.active { display: block; }

#relay-list { display: flex; flex-direction: column; gap: 6px; }
.relay-row {
display: flex; align-items: center; gap: 8px;
background: var(--surface2);
padding: 6px 10px;
border-radius: 4px;
flex-wrap: wrap;
}
.relay-row .url { flex: 1; font-family: 'IBM Plex Mono', monospace; font-size: 0.82rem; min-width: 200px; }
.relay-row .status {
font-size: 0.72rem;
font-family: 'IBM Plex Mono', monospace;
padding: 2px 6px;
border-radius: 3px;
min-width: 88px;
text-align: center;
}
.status.disconnected { background: #444; color: var(--muted); }
.status.connecting { background: var(--purple); color: white; }
.status.open { background: var(--green); color: white; }
.status.error { background: var(--red); color: white; }
.relay-row .msgs { font-size: 0.72rem; color: var(--muted); min-width: 60px; }

textarea { width: 100%; min-height: 70px; resize: vertical; }

#event-log {
max-height: 600px;
overflow-y: auto;
font-family: 'IBM Plex Mono', monospace;
font-size: 0.78rem;
}
.log-entry {
padding: 6px 8px;
margin-bottom: 5px;
border-radius: 4px;
border-left: 3px solid;
}
.log-entry.in { background: rgba(91,192,222,0.05); border-left-color: var(--blue); }
.log-entry.out { background: rgba(245,166,35,0.05); border-left-color: var(--accent); }
.log-entry.system { background: rgba(112,112,112,0.08); border-left-color: var(--muted); }
.log-entry.error { background: rgba(217,83,79,0.05); border-left-color: var(--red); }
.log-entry .head {
color: var(--subtext);
font-size: 0.72rem;
margin-bottom: 3px;
}
.log-entry .summary { color: var(--text); margin-bottom: 4px; word-break: break-word; }
.log-entry pre {
margin: 0;
white-space: pre-wrap;
word-break: break-all;
background: var(--bg);
padding: 6px;
border-radius: 3px;
color: var(--subtext);
max-height: 240px;
overflow-y: auto;
cursor: pointer;
font-size: 0.74rem;
}
.log-entry pre.collapsed { max-height: 38px; overflow: hidden; }
.log-entry .relay-tag {
display: inline-block;
background: var(--surface);
padding: 1px 6px;
border-radius: 3px;
font-size: 0.7rem;
color: var(--accent);
margin-right: 4px;
}
.identity-display {
font-family: 'IBM Plex Mono', monospace;
font-size: 0.82rem;
word-break: break-all;
background: var(--surface2);
padding: 8px 10px;
border-radius: 4px;
}
.identity-display strong { color: var(--accent); display: inline-block; min-width: 110px; }
.muted { color: var(--muted); }
small.help-inline { color: var(--muted); font-size: 0.75rem; margin-left: 4px; }
</style>
</head>
<body>
<header>
<h1>Nostr Hands-On</h1>
<p>A bare-metal Nostr learning page. One file, no install, no client opinions, no follow lists, no profile rendering. Every WebSocket message is logged in section 5 <strong>and mirrored to the browser console</strong> (open DevTools / F12). Read the source — it <em>is</em> the tutorial.</p>
</header>

<section>
<h2>1. Identity — load a private key</h2>
<div class="help">Paste your <code>nsec1...</code> or 64-char hex private key. The key stays in this tab's memory only — it's never sent to any server, written to disk, or kept after you close the tab.</div>
<div class="warn"><strong>⚠ Use a disposable key.</strong> The privkey lives in plain JS memory while this tab is open. Browser extensions, page bugs, or future you forgetting which tab is which can all expose it. For real Nostr usage, use a NIP-07 extension (nos2x / Alby) — see the wiki.</div>
<div class="row">
<input id="nsec-input" type="password" placeholder="nsec1... or 64-char hex" autocomplete="off">
<button id="load-key" class="primary">Load Key</button>
<button id="forget-key">Forget</button>
</div>
<div id="identity-out" class="identity-display muted">No key loaded.</div>
</section>

<section>
<h2>2. Relays — open WebSockets</h2>
<div class="help">Pick which relays to use. Click <strong>Connect</strong> on each one. Status flips disconnected → connecting → open. Read-only relays don't need your key. Write relays need your pubkey on the relay's whitelist (for your private relays, that means you set them up correctly in <code>config.toml</code>).</div>
<div id="relay-list"></div>
<div class="row" style="margin-top:10px;">
<input id="new-relay" placeholder="wss://your-relay.example.com" autocomplete="off">
<button id="add-relay">Add relay</button>
</div>
<div class="tip">A "Connect" failure is almost always: bad URL, relay offline, or your network blocking outbound 443. Check the system log entry for the WebSocket error.</div>
</section>

<section>
<h2>3. Compose — sign and publish events</h2>
<div class="help">Build a Nostr event, sign it with your loaded key, and broadcast to every <em>open</em> relay. The signed event is logged in section 5 — check the JSON to see <code>id</code> (sha256 of canonical fields), <code>sig</code> (schnorr), <code>tags</code>, etc.</div>
<div class="tab-buttons">
<button class="tab-btn active" data-tab="note">Public Note (kind 1)</button>
<button class="tab-btn" data-tab="dm">DM (kind 4 / NIP-04)</button>
</div>
<div class="tab-pane active" data-pane="note">
<textarea id="note-content" placeholder="What's on your mind? (kind 1 = a public note. The whole world can read this on any relay you publish to.)"></textarea>
<div class="row" style="margin-top:8px;">
<button id="send-note" class="primary">Sign & Publish</button>
<small class="help-inline">Goes to every relay currently in the open state.</small>
</div>
</div>
<div class="tab-pane" data-pane="dm">
<input id="dm-recipient" placeholder="Recipient npub1... or 64-char hex" autocomplete="off">
<textarea id="dm-content" placeholder="Encrypted message body" style="margin-top:6px;"></textarea>
<div class="row" style="margin-top:8px;">
<button id="send-dm" class="primary">Encrypt, Sign & Publish</button>
<small class="help-inline">NIP-04: end-to-end encrypted. Relays see the ciphertext + the recipient's pubkey, not the body.</small>
</div>
<div class="tip">NIP-04 is the original DM scheme — old, deprecated for new clients (NIP-17 is the modern one), but transparent and supported everywhere. Good for learning. <strong>Do not</strong> use it as your main DM transport long-term.</div>
</div>
</section>

<section>
<h2>4. Subscribe — ask relays for events</h2>
<div class="help">A subscription is a <code>REQ</code> message with one or more filter objects. Relays send matching stored events, then <code>EOSE</code> (end of stored events), then keep streaming new matches in real time until you <code>CLOSE</code>.</div>
<div class="row">
<button class="sub-preset" data-preset="my-events">My events</button>
<button class="sub-preset" data-preset="my-dms">DMs to me</button>
<button class="sub-preset" data-preset="lookup-author">Lookup author…</button>
<button class="sub-preset" data-preset="firehose">Firehose (latest 20 kind 1)</button>
<button id="cancel-subs" class="danger">Cancel all subs</button>
</div>
<div id="active-subs" class="muted" style="margin-top: 8px; font-size: 0.78rem;"></div>
<div class="tip">Filters are JSON predicates: <code>{kinds:[1], authors:[hex]}</code>, <code>{kinds:[4], "#p":[my-hex]}</code>, etc. Relays AND the conditions inside a filter, OR across multiple filters in one REQ.</div>
</section>

<section>
<h2>5. Event Log — every WebSocket message in/out</h2>
<div class="help">Click any JSON block to expand/collapse. Browser console (F12) gets the same data — useful for searching with Ctrl+F. Outgoing in <span style="color:var(--accent)">orange</span>, incoming in <span style="color:var(--blue)">blue</span>, system in grey, errors in red.</div>
<div class="row">
<button id="clear-log">Clear log</button>
<label style="font-size:0.82rem;"><input type="checkbox" id="show-raw" checked> Show raw JSON</label>
</div>
<div id="event-log"></div>
</section>

<script type="module">
// ============================================================================
// Imports — pure browser ESM via esm.sh, no install, no build step.
// ============================================================================
//
// nostr-tools gives us: schnorr signing, schnorr verification, sha256 event-id,
// bech32 (npub/nsec) encode/decode, and NIP-04 ECDH+AES encryption.
// We deliberately use raw WebSockets (not the nostr-tools Relay class) so the
// REQ/EVENT/EOSE/OK/NOTICE/CLOSE wire dance is fully visible.
//
// Pinned to a specific 2.x version so this file keeps working when nostr-tools
// 3.x ships with breaking changes.
import {
finalizeEvent, // adds id + sig to an unsigned event
getPublicKey, // priv (Uint8Array) -> hex pubkey
verifyEvent, // validates id + sig
nip04, // .encrypt(priv, theirPub, plain) / .decrypt(priv, theirPub, cipher)
nip19 // .npubEncode / .nsecEncode / .decode
} from 'https://esm.sh/nostr-tools@2.7.2';

// ============================================================================
// State
// ============================================================================

const state = {
privkey: null, // Uint8Array(32) — null until a key is loaded
pubkey: null, // hex string (64 chars)
npub: null, // bech32 npub
relays: new Map(), // url -> { ws, status, msgs }
subs: new Map() // subId -> { filters }
};

const DEFAULT_RELAYS = [
'wss://nostr.hive-book.com',
'wss://nostr.v4call.com',
'wss://relay.damus.io',
'wss://nos.lol'
];

// ============================================================================
// Tiny helpers
// ============================================================================

function hexToBytes(hex) {
if (hex.length % 2) throw new Error('hex string odd length');
const out = new Uint8Array(hex.length / 2);
for (let i = 0; i < out.length; i++) out[i] = parseInt(hex.slice(i*2, i*2+2), 16);
return out;
}
function shortKey(hex) { return hex ? hex.slice(0, 8) + '…' + hex.slice(-4) : ''; }
function shortNpub(npub) { return npub ? npub.slice(0, 12) + '…' + npub.slice(-4) : ''; }
function nowSec() { return Math.floor(Date.now() / 1000); }
function timeStr() {
const d = new Date();
return d.toTimeString().slice(0,8) + '.' + String(d.getMilliseconds()).padStart(3,'0');
}
function escapeHtml(s) {
return String(s).replace(/[&<>"']/g, c => ({
'&':'&','<':'<','>':'>','"':'"',"'":'''
}[c]));
}

// ============================================================================
// Logging — every WS in/out shows up here AND in console.log
// ============================================================================

const logEl = document.getElementById('event-log');

function addLog({ type, relay, summary, raw }) {
const showRaw = document.getElementById('show-raw').checked;
const div = document.createElement('div');
div.className = 'log-entry ' + type;
let html = `<div class="head">${timeStr()} `;
if (relay) html += `<span class="relay-tag">${escapeHtml(relay)}</span> `;
html += `<span class="muted">${type.toUpperCase()}</span></div>`;
if (summary) html += `<div class="summary">${escapeHtml(summary)}</div>`;
if (raw && showRaw) {
let pretty;
try {
const obj = (typeof raw === 'string') ? JSON.parse(raw) : raw;
pretty = JSON.stringify(obj, null, 2);
} catch { pretty = String(raw); }
html += `<pre class="collapsed">${escapeHtml(pretty)}</pre>`;
}
div.innerHTML = html;
logEl.prepend(div);
const pre = div.querySelector('pre');
if (pre) pre.addEventListener('click', () => pre.classList.toggle('collapsed'));
// mirror to browser console for grep / Ctrl+F
console.log(`[${type}]`, relay || '-', summary || '', raw ?? '');
}

// ============================================================================
// Identity
// ============================================================================

const idOut = document.getElementById('identity-out');

document.getElementById('load-key').addEventListener('click', () => {
const raw = document.getElementById('nsec-input').value.trim();
if (!raw) return;
try {
let priv;
if (raw.startsWith('nsec1')) {
const decoded = nip19.decode(raw);
if (decoded.type !== 'nsec') throw new Error('not an nsec');
priv = decoded.data; // Uint8Array(32)
} else if (/^[0-9a-f]{64}$/i.test(raw)) {
priv = hexToBytes(raw.toLowerCase());
} else {
throw new Error('paste an nsec1... or 64-char hex');
}
state.privkey = priv;
state.pubkey = getPublicKey(priv);
state.npub = nip19.npubEncode(state.pubkey);
idOut.classList.remove('muted');
idOut.innerHTML = `
<div><strong>npub</strong> ${escapeHtml(state.npub)}</div>
<div><strong>hex pubkey</strong> ${escapeHtml(state.pubkey)}</div>
`;
addLog({ type:'system', summary:`Loaded identity ${shortNpub(state.npub)}`, raw:{ npub: state.npub, pubkey: state.pubkey } });
document.getElementById('nsec-input').value = '';
} catch (e) {
addLog({ type:'error', summary:`Failed to load key: ${e.message}`, raw:null });
alert('Bad key: ' + e.message);
}
});

document.getElementById('forget-key').addEventListener('click', () => {
state.privkey = null;
state.pubkey = null;
state.npub = null;
idOut.classList.add('muted');
idOut.textContent = 'No key loaded.';
addLog({ type:'system', summary:'Identity forgotten (privkey wiped from memory).', raw:null });
});

// ============================================================================
// Relays
// ============================================================================

const relayListEl = document.getElementById('relay-list');

function renderRelayRow(url) {
const r = state.relays.get(url) || { ws:null, status:'disconnected', msgs:0 };
let row = relayListEl.querySelector(`[data-url="${CSS.escape(url)}"]`);
if (!row) {
row = document.createElement('div');
row.className = 'relay-row';
row.dataset.url = url;
row.innerHTML = `
<span class="url">${escapeHtml(url)}</span>
<span class="status disconnected">disconnected</span>
<span class="msgs"></span>
<button class="connect-btn">Connect</button>
<button class="disconnect-btn" style="display:none;">Disconnect</button>
<button class="remove-btn" title="Remove">×</button>
`;
relayListEl.appendChild(row);
row.querySelector('.connect-btn').addEventListener('click', () => connectRelay(url));
row.querySelector('.disconnect-btn').addEventListener('click', () => disconnectRelay(url));
row.querySelector('.remove-btn').addEventListener('click', () => {
disconnectRelay(url);
state.relays.delete(url);
row.remove();
});
}
const statusEl = row.querySelector('.status');
statusEl.className = 'status ' + r.status;
statusEl.textContent = r.status;
row.querySelector('.msgs').textContent = r.msgs ? `${r.msgs} msgs` : '';
const open = (r.status === 'open' || r.status === 'connecting');
row.querySelector('.connect-btn').style.display = open ? 'none' : '';
row.querySelector('.disconnect-btn').style.display = open ? '' : 'none';
}

function connectRelay(url) {
let r = state.relays.get(url);
if (!r) { r = { ws:null, status:'disconnected', msgs:0 }; state.relays.set(url, r); }
if (r.ws && (r.ws.readyState === WebSocket.CONNECTING || r.ws.readyState === WebSocket.OPEN)) return;
r.status = 'connecting';
renderRelayRow(url);
addLog({ type:'system', relay:url, summary:'Connecting…', raw:null });
let ws;
try {
ws = new WebSocket(url);
} catch (e) {
r.status = 'error';
addLog({ type:'error', relay:url, summary:e.message, raw:null });
renderRelayRow(url);
return;
}
r.ws = ws;
ws.addEventListener('open', () => {
r.status = 'open';
addLog({ type:'system', relay:url, summary:'WebSocket open.', raw:null });
renderRelayRow(url);
// Re-attach existing subs to the newly opened relay
for (const [subId, sub] of state.subs) {
const msg = ['REQ', subId, ...sub.filters];
ws.send(JSON.stringify(msg));
addLog({ type:'out', relay:url, summary:`REQ ${subId} (re-attached)`, raw:msg });
}
});
ws.addEventListener('message', (ev) => {
r.msgs++;
renderRelayRow(url);
let parsed;
try { parsed = JSON.parse(ev.data); }
catch { addLog({ type:'in', relay:url, summary:'non-JSON message', raw:ev.data }); return; }
handleRelayMessage(url, parsed);
});
ws.addEventListener('close', () => {
r.status = 'disconnected';
addLog({ type:'system', relay:url, summary:'WebSocket closed.', raw:null });
renderRelayRow(url);
});
ws.addEventListener('error', () => {
r.status = 'error';
addLog({ type:'error', relay:url, summary:'WebSocket error (DNS / TLS / blocked port?)', raw:null });
renderRelayRow(url);
});
}

function disconnectRelay(url) {
const r = state.relays.get(url);
if (r && r.ws) { try { r.ws.close(); } catch {} }
}

function handleRelayMessage(url, msg) {
if (!Array.isArray(msg)) {
addLog({ type:'in', relay:url, summary:'unknown shape', raw:msg });
return;
}
const verb = msg[0];
if (verb === 'EVENT') {
const [, subId, ev] = msg;
let summary = `EVENT sub=${subId} kind=${ev.kind} from=${shortKey(ev.pubkey)}`;
// Auto-decrypt kind 4 if I can
if (ev.kind === 4 && state.privkey) {
const myHex = state.pubkey;
const iAmRecipient = ev.tags.some(t => t[0] === 'p' && t[1] === myHex);
const iAmSender = ev.pubkey === myHex;
if (iAmRecipient || iAmSender) {
const counterparty = iAmRecipient ? ev.pubkey : (ev.tags.find(t => t[0] === 'p') || [])[1];
if (counterparty) {
nip04.decrypt(state.privkey, counterparty, ev.content)
.then(plain => {
const tag = iAmRecipient ? `from ${shortKey(ev.pubkey)}` : `to ${shortKey(counterparty)}`;
addLog({ type:'in', relay:url, summary:`DM (decrypted) ${tag}: ${plain}`, raw:ev });
})
.catch(e => addLog({ type:'in', relay:url, summary:`${summary} — decrypt failed: ${e.message}`, raw:ev }));
return;
}
}
}
if (ev.kind === 1) summary += ` content="${(ev.content || '').slice(0, 80).replace(/\n/g,' ')}"`;
addLog({ type:'in', relay:url, summary, raw:ev });
} else if (verb === 'EOSE') {
addLog({ type:'in', relay:url, summary:`EOSE sub=${msg[1]} (end of stored events; live updates continue)`, raw:msg });
} else if (verb === 'OK') {
const [, eventId, accepted, reason] = msg;
addLog({ type:'in', relay:url, summary:`OK ${shortKey(eventId)} accepted=${accepted}${reason ? ' reason="'+reason+'"' : ''}`, raw:msg });
} else if (verb === 'NOTICE') {
addLog({ type:'in', relay:url, summary:`NOTICE: ${msg[1]}`, raw:msg });
} else if (verb === 'CLOSED') {
addLog({ type:'in', relay:url, summary:`CLOSED sub=${msg[1]}${msg[2] ? ' reason="'+msg[2]+'"' : ''}`, raw:msg });
} else {
addLog({ type:'in', relay:url, summary:`unknown verb ${verb}`, raw:msg });
}
}

document.getElementById('add-relay').addEventListener('click', () => {
const url = document.getElementById('new-relay').value.trim();
if (!url) return;
if (!/^wss?:\/\//.test(url)) { alert('URL must start with wss:// or ws://'); return; }
if (!state.relays.has(url)) state.relays.set(url, { ws:null, status:'disconnected', msgs:0 });
renderRelayRow(url);
document.getElementById('new-relay').value = '';
});

DEFAULT_RELAYS.forEach(url => {
state.relays.set(url, { ws:null, status:'disconnected', msgs:0 });
renderRelayRow(url);
});

// ============================================================================
// Tabs
// ============================================================================

document.querySelectorAll('.tab-btn').forEach(btn => {
btn.addEventListener('click', () => {
document.querySelectorAll('.tab-btn').forEach(b => b.classList.remove('active'));
document.querySelectorAll('.tab-pane').forEach(p => p.classList.remove('active'));
btn.classList.add('active');
document.querySelector(`[data-pane="${btn.dataset.tab}"]`).classList.add('active');
});
});

// ============================================================================
// Compose: public note (kind 1)
// ============================================================================

document.getElementById('send-note').addEventListener('click', () => {
if (!state.privkey) return alert('Load your key in section 1 first.');
const content = document.getElementById('note-content').value;
if (!content.trim()) return alert('Note is empty.');

// Build the unsigned event. Per NIP-01, an event has these fields:
// pubkey, created_at, kind, tags, content
// (id and sig are added by finalizeEvent.)
const unsigned = {
kind: 1,
created_at: nowSec(),
tags: [],
content
};
// finalizeEvent does:
// 1. set pubkey from priv
// 2. compute id = sha256( JSON([0, pubkey, created_at, kind, tags, content]) )
// 3. sign id with schnorr (BIP-340) using priv
// 4. attach id + sig to the event
const signed = finalizeEvent(unsigned, state.privkey);
if (!verifyEvent(signed)) {
addLog({ type:'error', summary:'verifyEvent failed — refusing to publish (this should never happen)', raw:signed });
return;
}
publishEvent(signed);
document.getElementById('note-content').value = '';
});

// ============================================================================
// Compose: DM (kind 4 NIP-04)
// ============================================================================

document.getElementById('send-dm').addEventListener('click', async () => {
if (!state.privkey) return alert('Load your key in section 1 first.');
const recipRaw = document.getElementById('dm-recipient').value.trim();
const body = document.getElementById('dm-content').value;
if (!recipRaw || !body.trim()) return alert('Need both recipient and message.');

let recipHex;
try {
if (recipRaw.startsWith('npub1')) {
const dec = nip19.decode(recipRaw);
if (dec.type !== 'npub') throw new Error('not an npub');
recipHex = dec.data;
} else if (/^[0-9a-f]{64}$/i.test(recipRaw)) {
recipHex = recipRaw.toLowerCase();
} else throw new Error('paste an npub1... or hex pubkey');
} catch (e) {
return alert('Bad recipient: ' + e.message);
}

// NIP-04: ECDH(my-priv, their-pub) -> shared secret -> AES-CBC encrypt(body)
// -> content = base64(ciphertext) + "?iv=" + base64(iv)
let ciphertext;
try {
ciphertext = await nip04.encrypt(state.privkey, recipHex, body);
} catch (e) {
addLog({ type:'error', summary:`NIP-04 encrypt failed: ${e.message}`, raw:{ recipient: recipHex, error: e.message } });
alert('Encrypt failed: ' + e.message + '\n\nUsually means a bad recipient pubkey.');
return;
}

const unsigned = {
kind: 4,
created_at: nowSec(),
tags: [['p', recipHex]], // 'p' tag tells relays who the recipient is (visible plaintext!)
content: ciphertext
};
let signed;
try {
signed = finalizeEvent(unsigned, state.privkey);
} catch (e) {
addLog({ type:'error', summary:`finalizeEvent failed: ${e.message}`, raw:unsigned });
return;
}
if (!verifyEvent(signed)) {
addLog({ type:'error', summary:'verifyEvent failed — refusing to publish', raw:signed });
return;
}
publishEvent(signed);
document.getElementById('dm-content').value = '';
});

function publishEvent(signed) {
const msg = ['EVENT', signed];
let sent = 0;
for (const [url, r] of state.relays) {
if (r.ws && r.ws.readyState === WebSocket.OPEN) {
r.ws.send(JSON.stringify(msg));
sent++;
addLog({ type:'out', relay:url, summary:`EVENT kind=${signed.kind} id=${shortKey(signed.id)}`, raw:msg });
}
}
if (!sent) addLog({ type:'error', summary:'No open relays — nothing was published. Connect a relay in section 2.', raw:signed });
}

// ============================================================================
// Subscribe presets
// ============================================================================

let subCounter = 0;
function nextSubId() { return `sub-${++subCounter}`; }

function publishSub(filters) {
const subId = nextSubId();
state.subs.set(subId, { filters });
const msg = ['REQ', subId, ...filters];
let sent = 0;
for (const [url, r] of state.relays) {
if (r.ws && r.ws.readyState === WebSocket.OPEN) {
r.ws.send(JSON.stringify(msg));
addLog({ type:'out', relay:url, summary:`REQ ${subId}`, raw:msg });
sent++;
}
}
if (!sent) addLog({ type:'error', summary:'No open relays — REQ not sent.', raw:msg });
renderActiveSubs();
}

document.querySelectorAll('.sub-preset').forEach(btn => {
btn.addEventListener('click', () => {
const preset = btn.dataset.preset;
if (preset === 'my-events') {
if (!state.pubkey) return alert('Load key first.');
publishSub([{ kinds:[0,1,3,4,7], authors:[state.pubkey], limit:50 }]);
} else if (preset === 'my-dms') {
if (!state.pubkey) return alert('Load key first.');
publishSub([{ kinds:[4], '#p':[state.pubkey], limit:50 }]);
} else if (preset === 'lookup-author') {
const raw = prompt('Author npub or 64-char hex:');
if (!raw) return;
let hex;
try {
if (raw.startsWith('npub1')) {
const d = nip19.decode(raw.trim());
if (d.type !== 'npub') throw new Error('not an npub');
hex = d.data;
} else if (/^[0-9a-f]{64}$/i.test(raw.trim())) {
hex = raw.trim().toLowerCase();
} else throw new Error('bad input');
} catch (e) { return alert(e.message); }
publishSub([{ kinds:[0,1], authors:[hex], limit:30 }]);
} else if (preset === 'firehose') {
publishSub([{ kinds:[1], limit:20 }]);
}
});
});

document.getElementById('cancel-subs').addEventListener('click', () => {
for (const [subId] of state.subs) {
const msg = ['CLOSE', subId];
for (const [url, r] of state.relays) {
if (r.ws && r.ws.readyState === WebSocket.OPEN) {
r.ws.send(JSON.stringify(msg));
addLog({ type:'out', relay:url, summary:`CLOSE ${subId}`, raw:msg });
}
}
}
state.subs.clear();
renderActiveSubs();
});

function renderActiveSubs() {
const el = document.getElementById('active-subs');
if (!state.subs.size) { el.textContent = 'No active subscriptions.'; return; }
el.textContent = `Active subs: ${Array.from(state.subs.keys()).join(', ')}`;
}
renderActiveSubs();

// ============================================================================
// Misc
// ============================================================================

document.getElementById('clear-log').addEventListener('click', () => { logEl.innerHTML = ''; });

addLog({ type:'system', summary:'Page loaded. Open the browser console (F12) to see all WebSocket traffic mirrored there.', raw:null });
</script>
</body>
</html>
</pre>
</div>
</div>

== Why a hands-on page beats a real client for learning ==

* Real clients pick relays for you, sign for you, decrypt for you, render for you. Magic = mystery = doesn't stick.
* This page does ''nothing'' automatically. You connect each relay manually. You build each event manually. You pick filters manually. You see every signed JSON object before it leaves and after it arrives.
* The whole thing is one HTML file with all logic in plain ES modules. <code>view-source:</code> in the browser ''is'' the tutorial. Read the comments inline as you click through the lessons.
* When you ''do'' graduate to a real client, you'll know exactly what each setting in "Relays" / "DM" / "Notifications" maps to in the protocol.

== Contents ==

* [[#Prerequisites|1 Prerequisites]]
* [[#Step_0:_Open_the_page|2 Step 0: Open the page (no install)]]
* [[#Lesson_1:_Load_a_key|3 Lesson 1: Load a key]]
* [[#Lesson_2:_Connect_a_relay|4 Lesson 2: Connect a relay]]
* [[#Lesson_3:_Publish_your_first_public_note|5 Lesson 3: Publish your first public note]]
* [[#Lesson_4:_Verify_on_the_server_with_nak|6 Lesson 4: Verify on the server with nak]]
* [[#Lesson_5:_Subscribe_to_your_own_feed|7 Lesson 5: Subscribe to your own feed]]
* [[#Lesson_6:_Open_a_second_identity_in_a_second_window|8 Lesson 6: Open a second identity in a second window]]
* [[#Lesson_7:_Have_a_public-note_conversation|9 Lesson 7: Have a public-note conversation]]
* [[#Lesson_8:_Send_an_encrypted_DM|10 Lesson 8: Send an encrypted DM (NIP-04)]]
* [[#Lesson_9:_Read_the_raw_JSON|11 Lesson 9: Read the raw JSON]]
* [[#Lesson_10:_Watch_the_firehose|12 Lesson 10: Watch the firehose (a public relay)]]
* [[#Lesson_11:_Server-side_view|13 Lesson 11: Server-side view (Docker logs + nak)]]
* [[#Lesson_12:_Break_things_on_purpose|14 Lesson 12: Break things on purpose]]
* [[#What_this_page_does_NOT_do|15 What this page does NOT do]]
* [[#Wisdom_for_the_Nostr_Noob|16 Wisdom for the Nostr Noob]]
* [[#Where_to_go_after_this|17 Where to go after this]]

== Prerequisites ==

* '''Two relays from stage 1 working''' — <code>wss://nostr.hive-book.com</code> and <code>wss://nostr.v4call.com</code> (or your equivalents).
* '''Three nsec keys''' generated and whitelisted on both relays. Stage 1 covered this. The keys can be from <code>nostr-gen.html</code>, your normal Nostr client, or <code>nak key generate</code>.
* '''nak installed on your laptop''' (Stage 1 → Step 14 → Option 1C). Used in lessons 4 + 11.
* '''A modern browser with developer tools''' — Brave, Firefox, Chrome, Safari all work. We'll reference Brave in screenshots since that's CompleteNoobs' default.
* '''nostr-handson.html''' — sitting in this folder next to this wiki.

== Step 0: Open the page (no install) ==

Three ways to load <code>nostr-handson.html</code>; pick whichever you prefer:

;'''Option A — file:// (simplest)'''
:Just double-click the file in your file manager, or drag it into a browser tab. Address bar will show <code>file:///path/to/nostr-handson.html</code>. WebSocket-to-internet works fine from <code>file://</code>; no special server needed.

;'''Option B — <code>python3 -m http.server</code> (if you prefer http://)'''
:From the folder containing the file:
: <code>python3 -m http.server 8000</code>
:Then browse to <code>http://localhost:8000/nostr-handson.html</code>.

;'''Option C — Host it on your relay box''' (clean URL, accessible from any device)
:Drop the file into your relay's web root and serve via Caddy. Out of scope for this lesson; do it later if you want.

The page imports its crypto + bech32 helpers from <code>esm.sh</code> on first load — that's a CDN fetch of <code>nostr-tools</code>. After that the page is fully functional even offline (until cache expires). '''Open the browser console (F12) before you click anything.'''

== Lesson 1: Load a key ==

# In Section 1, paste an <code>nsec1...</code> from one of your three whitelisted keys. Use a '''disposable / learning''' key — see the warning in the page.
# Click <strong>Load Key</strong>.
# The page derives + displays your <code>npub</code> and your hex pubkey.
# Open your browser console — there's a system log line: <code>[system] - Loaded identity npub1abc…xyz4 {npub: ..., pubkey: ...}</code>.

;'''What just happened'''
* <code>nip19.decode("nsec1...")</code> turned your bech32 nsec into raw bytes.
* <code>getPublicKey(privBytes)</code> ran a single secp256k1 scalar multiplication to derive your pubkey. Same math underlies BTC, ETH, Hive — Nostr just uses the result differently.
* <code>nip19.npubEncode(pubkeyHex)</code> wrapped the pubkey in bech32 to get your <code>npub</code>.
* The privkey is now sitting in <code>state.privkey</code> in browser memory. Closing the tab forgets it.

;'''💡 Wisdom'''
:'''An npub and a hex pubkey are the same key, just two encodings.''' Relays use hex internally. Clients display npub. Always 64 hex chars / always starts <code>npub1</code>. If you only see one form, you can convert any time with <code>nak decode npub1...</code>.

== Lesson 2: Connect a relay ==

# In Section 2 you'll see four pre-filled relays — your two privates plus <code>relay.damus.io</code> and <code>nos.lol</code> (popular publics).
# Click <strong>Connect</strong> on <code>wss://nostr.hive-book.com</code> (or whichever of yours).
# Status flips: <code>disconnected</code> → <code>connecting</code> → <code>open</code> (green).
# Console gets one <code>[system]</code> entry per state change.

;'''What just happened'''
* <code>new WebSocket("wss://nostr.hive-book.com")</code> opened a TCP/TLS/WebSocket-upgrade chain to the relay.
* The browser dev tools' <strong>Network</strong> tab → filter <strong>WS</strong> shows the connection. Click it → <strong>Messages</strong> sub-tab shows every frame in/out. Useful as a second view alongside section 5.

;'''💡 Wisdom'''
:'''A Nostr connection is just a WebSocket.''' Same plumbing as a chat room, a stock ticker, or a multiplayer game. Nothing magical at the transport layer. The protocol on top of it (REQ / EVENT / EOSE / OK / NOTICE / CLOSED) is what's "Nostr-y".

== Lesson 3: Publish your first public note ==

# Section 3 → "Public Note (kind 1)" tab is selected by default.
# Type something memorable: <code>hello world from nostr-handson</code>.
# Click <strong>Sign & Publish</strong>.
# Watch sections 5 + the console:
:* <code>[out] EVENT kind=1 id=abc123…</code> with the full JSON.
:* Then a <code>[in] OK abc123… accepted=true</code> from each connected relay.

;'''What just happened — the most important JSON in Nostr'''
:Click the JSON block in the log to expand. You'll see something like:
{
"kind": 1,
"created_at": 1746554000,
"tags": [],
"content": "hello world from nostr-handson",
"pubkey": "abc123…", // hex pubkey, derived from your nsec
"id": "deadbeef…", // sha256 of [0,pubkey,created_at,kind,tags,content]
"sig": "f00ba12…" // schnorr signature of id, by your privkey
}
:'''The id and sig are the whole proof.''' Anyone in the world holding only this JSON can verify it actually came from your pubkey and hasn't been tampered with — without ever talking to you, the relay, or anything.

;'''💡 Wisdom'''
:'''A Nostr event is just signed JSON.''' That's it. Every "post" / "DM" / "reaction" / "follow list" / "long-form article" / "zap receipt" / etc. is the same shape: a JSON object with <code>kind</code> picking the type, <code>tags</code> attaching metadata, and <code>content</code> being the body. Hundreds of kinds defined across NIPs, all the same fundamental wrapper.

== Lesson 4: Verify on the server with nak ==

You don't have to trust the page — go look at the relay directly.

nak req -k 1 -a YOUR_HEX_PUBKEY wss://nostr.hive-book.com

(Use the hex pubkey from section 1 of the page, not the npub.)

You should see your note printed. nak hits the WebSocket, sends a REQ with <code>kinds:[1], authors:[your-hex]</code>, prints every EVENT, then exits on EOSE.

;'''💡 Wisdom'''
:'''Whenever a client claims something is missing, query the relay directly.''' If nak finds the event but your client doesn't show it, the bug is in the client's relay config or filter, not in your publish. This single habit will save you days of debugging later.

== Lesson 5: Subscribe to your own feed ==

# Section 4 → click <strong>My events</strong>.
# Watch the log:
:* <code>[out] REQ sub-1</code> with filter <code>{kinds:[0,1,3,4,7], authors:[your-hex], limit:50}</code>.
:* <code>[in] EVENT sub=sub-1 kind=1 ...</code> — your note from lesson 3 comes back.
:* <code>[in] EOSE sub=sub-1</code> — "you've now seen all stored events; live updates continue."
# Now post another note from section 3. It'll arrive immediately on the same subscription as a live event.

;'''What just happened'''
:A Nostr subscription is a long-lived REQ. Stored events flow first, then EOSE marks the catch-up boundary, then the relay streams new matches in real time until you CLOSE.

;'''💡 Wisdom'''
:'''Filters AND across fields, OR across filter objects.''' <code>{kinds:[1], authors:[X]}</code> means "kind 1 AND author X". Adding a second filter to the same REQ means "match either filter". This is how clients build complex feeds (your follows + your replies + your zaps) in one subscription.

== Lesson 6: Open a second identity in a second window ==

You want to send a message between two of your three whitelisted accounts. Two ways to have two identities at once:

;'''Option A — Brave private window'''
:File → New Private Window. Open <code>nostr-handson.html</code> there. Load identity B's nsec.

;'''Option B — Two browsers'''
:Brave for identity A, Firefox for identity B (or any other combination).

You should now have ''two browser windows'', each showing the page, each with a different identity loaded. Treat them as Alice (account A) and Bob (account B).

# In Bob's window, connect <code>wss://nostr.v4call.com</code> (Bob's home relay) AND <code>wss://nostr.hive-book.com</code> (so Bob can read what Alice writes).
# In Alice's window, do the symmetrical: connect both relays.

;'''💡 Wisdom'''
:'''The single biggest source of "Nostr is broken" frustration is no shared relay between sender and recipient.''' Get this dual-relay setup working in both windows and you've eliminated 90% of all multi-account Nostr issues.

== Lesson 7: Have a public-note conversation ==

# Alice's window: section 4 → <strong>Lookup author…</strong> → paste Bob's npub. A REQ goes out for kinds 0+1 from Bob.
# Bob's window: same in reverse. Look up Alice's npub.
# Now Alice posts: <code>"Hi Bob, can you see this?"</code> Section 5 in Bob's window shows the incoming EVENT within a second.
# Bob replies (still kind 1): <code>"Loud and clear, Alice."</code>
# Alice's incoming subscription picks it up.

;'''💡 Wisdom'''
:'''This is the entire feed mechanism in Nostr.''' A real client wraps it in nicer UX, threading, mute lists, follow lists, but the wire protocol is exactly what you're seeing. There is no central server, no API key, no rate limit beyond what each relay chooses.

== Lesson 8: Send an encrypted DM (NIP-04) ==

# Alice's window → section 3 → <strong>DM (kind 4 / NIP-04)</strong> tab.
# Recipient: paste Bob's npub.
# Body: <code>"this is a secret"</code>.
# Click <strong>Encrypt, Sign & Publish</strong>.
# Watch the outgoing event in section 5. Notice <code>content</code> is base64 ciphertext like <code>4QwT...?iv=Lk9P...</code>, not your plaintext. Notice <code>tags: [["p", "bob-hex"]]</code> — that's how the relay knows who to deliver to.
# In Bob's window: section 4 → <strong>DMs to me</strong>.
# Bob's subscription matches kind 4 with <code>#p</code> tag = Bob's hex. The relay sends Alice's encrypted event. Bob's page <strong>auto-decrypts</strong> because Bob's nsec is loaded. The log shows: <code>[in] DM (decrypted) from abc12345…wxyz: this is a secret</code>.

;'''What just happened'''
* '''Encryption (NIP-04 spec)''':
:* shared = ECDH(Alice-priv, Bob-pub) = secp256k1 point's X coordinate (32 bytes).
:* iv = 16 random bytes.
:* ciphertext = AES-256-CBC(shared, iv, plaintext).
:* content field = base64(ciphertext) + "?iv=" + base64(iv).
* '''Decryption''' is the same with Bob-priv + Alice-pub — ECDH gives the same shared secret in either direction. That's the magic of Diffie-Hellman.
* '''The relay sees''': sender pubkey, recipient pubkey (from p-tag), timestamp, ciphertext. It does NOT see the body.

;'''⚠ Wisdom — NIP-04 limits'''
:* Metadata (who-talks-to-whom + when + how often) is plaintext on the relay. A relay operator running a logger can build the social graph.
:* NIP-44 is a newer encryption (ChaCha20 + HKDF + HMAC). Better authenticated encryption. Most clients support it.
:* NIP-17 wraps NIP-44 in "gift wraps" (kind 1059) that hide sender + recipient on the relay. Modern best practice. Not implemented in this page yet — too complex for stage 2.
:* '''For real privacy use a client that supports NIP-17.''' This page is for ''learning'', not for OPSEC.

== Lesson 9: Read the raw JSON ==

Open the browser console (F12 → Console tab). Filter / search for <code>[in]</code> or <code>[out]</code>:

* '''An outgoing kind 1''' has the canonical structure from lesson 3.
* '''An outgoing kind 4''' is the same shape but: kind=4, content=ciphertext, tags=[["p", recipient]].
* '''An incoming EVENT''' is a 3-tuple: <code>["EVENT", subId, eventObject]</code>.
* '''An incoming OK''' is a 4-tuple: <code>["OK", eventId, accepted (bool), reason (string)]</code>. <code>accepted=false</code> with a clear reason is how relays reject (e.g. <code>"blocked: pubkey not authorized to publish"</code>).
* '''A NOTICE''' is a server-side gripe: <code>["NOTICE", "could not parse command"]</code>. You saw this in stage 1 lesson 14.

;'''Try this in the console''':
:After connecting a relay, type:
: <code>["EVENT", "fakeId"]</code> ← intentionally malformed
:Then send it manually:
: <code>state.relays.get('wss://nostr.hive-book.com').ws.send(JSON.stringify(["EVENT","fakeId"]))</code>
:You'll get a NOTICE back from the relay rejecting the malformed message. Your page literally bypasses no security to do this — you're just speaking the protocol directly.

;'''💡 Wisdom'''
:'''Once you can build and parse these JSON shapes by hand, you can write a Nostr client.''' That's the whole protocol. Everything else is UX.

== Lesson 10: Watch the firehose (a public relay) ==

# Make sure <code>wss://relay.damus.io</code> is connected (it's pre-filled).
# Section 4 → <strong>Firehose</strong> button. This sends <code>{kinds:[1], limit:20}</code> with no author filter.
# Watch the log fill with kind-1 notes from random Nostr users worldwide.
# Notice each one has a different <code>pubkey</code>. Each one is independently signed.

;'''💡 Wisdom'''
:'''A public relay is just a private relay without the whitelist.''' Same protocol, same code, same <code>nostr-rs-relay</code> binary on the other end (or its peers). Yours is private only because of three lines in <code>config.toml</code>.

== Lesson 11: Server-side view (Docker logs + nak) ==

SSH into your relay box. In one terminal:

cd /opt/nostr-relay && docker compose logs -f nostr-relay

In another terminal (or back on your laptop):

nak req -k 4 -a YOUR_HEX_PUBKEY wss://nostr.hive-book.com

Now from the page, send another note. Watch the docker logs — the relay's perspective: a connection arrives, an EVENT is received, it's persisted, an OK goes back. Send a kind 4 — same flow, but the relay only sees ciphertext.

Try this with a non-whitelisted key (load a fresh disposable nsec, try to publish): the relay logs the rejection, the page receives <code>OK accepted=false reason="blocked: ..."</code>.

;'''💡 Wisdom'''
:'''Relays are accountable infrastructure.''' You can audit exactly what you accepted and rejected. This is part of why people run their own — you control the policy and you can prove you're enforcing it.

== Lesson 12: Break things on purpose ==

Healthy thing to do — surface error paths so you'll recognise them later.

# '''Disconnect a relay, then publish.''' Page shows <code>[error] No open relays — nothing was published</code>.
# '''Publish without a key loaded.''' Page alerts. (Try this in the console too: clear <code>state.privkey</code> and click Send.)
# '''Subscribe with a malformed filter.''' From the console: <code>state.relays.get('wss://nostr.hive-book.com').ws.send(JSON.stringify(["REQ","junk",{"foo":"bar"}]))</code> — the relay either ignores or NOTICEs.
# '''Send a DM to yourself.''' Auto-decrypts. Useful for confirming the encrypt/decrypt round-trip works locally without involving a second account.
# '''Refresh the page mid-session.''' Privkey is forgotten. Relays disconnect. Section 5 clears. Nothing persists. Re-paste nsec and reconnect. (This is by design — keys never persist.)
# '''Cancel all subs, then post.''' The post still goes out (publishing is independent of subscriptions). Subs only affect ''reading''.

;'''💡 Wisdom'''
:'''Most "Nostr won't work" reports are one of: no key loaded, no relay open, sender/recipient relay mismatch, or a stale subscription.''' Once you've intentionally hit each of these in a controlled setting, you'll diagnose them in seconds in the wild.

== What this page does NOT do ==

Stage 2 deliberately stops where the protocol ends and where ''client UX'' begins. The page does NOT:

* Render profiles (kind 0 metadata) — you only see "from <hex>".
* Build threaded reply trees (NIP-10 e/p tag markers).
* Render reactions (kind 7) as little hearts.
* Auto-discover who's on which relay (NIP-65 outbox model).
* Show notifications, mentions, or unread counts.
* Handle long-form articles (kind 30023) with markdown.
* Send or receive zaps (NIP-57 Lightning).
* Use modern DMs (NIP-17 gift-wrapped). NIP-04 only.
* Maintain mute lists, follow lists, or any persistence between page loads.
* Use a NIP-07 browser extension for safer key handling.

Each of these is a layer that real clients add on top of the protocol. Once you're comfortable with what's happening here, every one of them makes sense as a small specific addition rather than as opaque magic.

== Wisdom for the Nostr Noob ==

;'''Use disposable keys for this page'''
:The privkey lives in browser JS memory. Acceptable for learning, not for valuable identities. For real use → NIP-07 extension (nos2x / Alby) or a remote signer (NIP-46 / Nsec.app).

;'''No shared relay = no message delivered'''
:If sender's writes and recipient's reads don't overlap, you're shouting into the void. There is no central postman. This is THE concept.

;'''The console is your second feed'''
:Section 5 is a curated UI; the browser console (F12) has every byte mirrored to <code>console.log()</code>. Use Ctrl+F to search across hundreds of events. Filter by <code>[in]</code> / <code>[out]</code> / <code>[system]</code> / <code>[error]</code>.

;'''Read the page source'''
:All logic is in one <code><script type="module"></code> block at the bottom of the file. ~600 lines, well-commented. Edit it. Add a button. Add a kind. The page is yours — break it, learn from breaking it.

;'''nak is the second tool you'll always reach for'''
:When the page says "I sent it", confirm with <code>nak req -k 1 -a HEX wss://...</code>. When the page says "nothing came back", confirm with the same command. The two tools cross-check each other and remove all "but the client said..." doubt.

;'''Kinds are the schema'''
:0 = profile, 1 = note, 3 = follow list, 4 = old DM, 5 = delete request, 6 = repost, 7 = reaction, 9735 = zap receipt, 10002 = relay list, 30023 = long-form article, 1059 = NIP-17 gift wrap, ... hundreds of NIPs. The full list lives at [https://github.com/nostr-protocol/nips github.com/nostr-protocol/nips]. Surprisingly readable.

;'''Time stamps are seconds, not milliseconds'''
:Nostr's <code>created_at</code> is Unix seconds (<code>Math.floor(Date.now()/1000)</code>). Putting milliseconds will make events look ~50 years in the future and many relays drop them.

;'''"Delete" is fuzzy'''
:NIP-09 has a "request deletion" event. Relays may or may not honour it. Other relays still have copies. Treat anything you publish as permanent.

== Where to go after this ==

In rough order of "what to learn next":

# '''NIP-65 outbox model''' — publish a relay-list event (kind 10002) declaring your read + write relays. This is the spec for "where can people find me." Most modern clients use it. Add a "publish my relay list" button to <code>nostr-handson.html</code> as a first hack.
# '''Profile metadata (kind 0)''' — set name, about, picture. Same shape as kind 1, but content is JSON. Replaceable: only the latest event survives per pubkey.
# '''NIP-05 verification''' — map <code>username@yourdomain.com</code> to your pubkey via a <code>/.well-known/nostr.json</code> on your domain. Stage 1's relays could host this trivially.
# '''NIP-07 (browser extension signing)''' — install nos2x or Alby. Modify <code>nostr-handson.html</code> so it calls <code>window.nostr.signEvent()</code> instead of holding the privkey. This is the right pattern for any real key.
# '''NIP-44 + NIP-17''' — modern DMs. NIP-44 = better symmetric encryption. NIP-17 = wrap NIP-44 in gift wraps so the relay can't see who-talked-to-whom.
# '''Zaps (NIP-57)''' — Lightning tipping over Nostr. You'll need a Lightning wallet first.
# '''A real client''' — Primal, nostrudel, Damus, Amethyst, Iris, Coracle, Snort, Habla. Pick one. Notice that under the hood it's doing exactly what your page does, just with prettier UX.
# '''v4call's planned Nostr layer''' — see [[V4call]] and the project's NOSTR-DESIGN-NOTES.md. Your private relays are the natural infrastructure for that, with one of your 3 keys being your v4call server's identity.

You now have a Nostr identity you understand, a relay you control, and a tool that exposes the entire protocol. That's a stronger foundation than 99% of Nostr users start with. 🌿

Nostr-relay-with-whitelist

2026-05-08T17:55:52Z

AwesomO: Created page with "{{:LICENCE_HEADER_MIT}} = Nostr Relay With a 3-Key Whitelist — Two Servers on Ubuntu 24.04 with Docker = From CompleteNoobs This guide walks through deploying '''two private Nostr relays''' from scratch on fresh Vultr Ubuntu 24.04 VPS boxes — one at <code>nostr.hive-book.com</code>, one at <code>nostr.v4call.com</code> — locked down so that only '''3 specific npub keys''' can publish events. The relays will serve over secure WebSocket (<code>wss://</code>) with..."

{{:LICENCE_HEADER_MIT}}

= Nostr Relay With a 3-Key Whitelist — Two Servers on Ubuntu 24.04 with Docker =

From CompleteNoobs

This guide walks through deploying '''two private Nostr relays''' from scratch on fresh Vultr Ubuntu 24.04 VPS boxes — one at <code>nostr.hive-book.com</code>, one at <code>nostr.v4call.com</code> — locked down so that only '''3 specific npub keys''' can publish events. The relays will serve over secure WebSocket (<code>wss://</code>) with auto-renewing Let's Encrypt certificates.

This is a "noob doing Nostr by doing" walkthrough. If you have never run a Nostr relay before, you are in the right place. The same steps work for one relay or fifty — repeat Steps 1–14 for each box, just with a different domain name.

'''End result''':
* <code>wss://nostr.hive-book.com</code> — accepts events only from your 3 whitelisted keys
* <code>wss://nostr.v4call.com</code> — accepts events only from your 3 whitelisted keys
* Anyone in the world can ''read'' events from these relays; only your 3 keys can ''write'' to them
* TLS certificates auto-renew, no manual fiddling

== Quick Background — What is a Nostr Relay? ==

If you are brand new to Nostr, here is the 60-second version:

* '''Nostr''' = "Notes and Other Stuff Transmitted by Relays". A simple decentralised protocol — no blockchain, no accounts to register, no central server.
* '''Identity''' is just a public key (an "npub", e.g. <code>npub1abc...xyz</code>). You sign your messages ("events") with your private key ("nsec"). Anyone can verify the signature with your npub.
* '''Relays''' are dumb servers that store and forward signed events. They do not own your identity. If one relay bans you, you publish to a different one. Your followers' clients query multiple relays and merge the results.
* '''Why run your own relay?''' Independence. Censorship-resistance. Speed. And — for this guide — the ability to run a ''private'' relay where only you (and your 2 friends, business partners, family — whoever holds the 3 whitelisted keys) can publish.

A "whitelisted-write, public-read" relay is a great starter project. Outsiders can't spam it; you and your trusted keys can post freely; the world can still read your events if they know the relay URL. It's also useful infrastructure for v4call's federation discovery layer (see [[V4call]]).

== Contents ==

* [[#What_You_Need|1 What You Need]]
* [[#Step_1:_Get_Your_3_Whitelisted_npubs_Ready|2 Step 1: Get Your 3 Whitelisted npubs Ready]]
* [[#Step_2:_Convert_npub_to_hex|3 Step 2: Convert npub to hex]]
* [[#Step_3:_Create_Your_Vultr_VPS_(x2)|4 Step 3: Create Your Vultr VPS (x2)]]
* [[#Step_4:_Point_Your_Domains_at_the_VPS_Boxes|5 Step 4: Point Your Domains at the VPS Boxes]]
* [[#Step_5:_Log_into_Your_VPS|6 Step 5: Log into Your VPS]]
* [[#Step_6:_Update_and_Secure_the_Server|7 Step 6: Update and Secure the Server]]
* [[#Step_7:_Install_Docker|8 Step 7: Install Docker]]
* [[#Step_8:_Open_the_Firewall|9 Step 8: Open the Firewall]]
* [[#Step_9:_Create_the_Relay_Project_Folder|10 Step 9: Create the Relay Project Folder]]
* [[#Step_10:_Write_the_Relay_Config|11 Step 10: Write the Relay Config (config.toml)]]
* [[#Step_11:_Write_the_Caddy_Config|12 Step 11: Write the Caddy Config (Caddyfile)]]
* [[#Step_12:_Write_the_docker-compose.yml|13 Step 12: Write the docker-compose.yml]]
* [[#Step_13:_Start_It_Up|14 Step 13: Start It Up]]
* [[#Step_14:_Test_the_Relay|15 Step 14: Test the Relay]]
* [[#Step_15:_Repeat_for_the_Second_Server|16 Step 15: Repeat for the Second Server]]
* [[#Updating_the_Whitelist|17 Updating the Whitelist]]
* [[#Common_Problems_and_Fixes|18 Common Problems and Fixes]]
* [[#Tips_for_Nostr_Noobs|19 Tips for Nostr Noobs]]

== What You Need ==

* '''A Vultr account''' — sign up at [https://vultr.com vultr.com]. Please use our [https://www.vultr.com/?ref=7704739 Vultr Referral link] to help cover server costs.
* '''Two domain names (or subdomains)''' with DNS access — for this guide: <code>nostr.hive-book.com</code> and <code>nostr.v4call.com</code>. Substitute your own.
* '''Three Nostr key pairs''' — the 3 npubs that will be allowed to publish. If you don't have them yet, see Step 1.
* '''A terminal''' — Mac: Terminal. Windows: PowerShell or PuTTY. Linux: whatever you've got.
* '''Around 30–45 minutes''' per server — most of which is waiting for DNS, apt updates, and Docker pulls.

You do not need to know Rust, Go, or any programming. Every command can be copy-pasted exactly as shown.

== Step 1: Get Your 3 Whitelisted npubs Ready ==

You need 3 Nostr public keys (npubs). These are the only keys that will be allowed to publish events to your relays.

If you don't have them yet, generate them. Pick whichever method you like:

;Option A — Browser-only generator (recommended, no install)
:If you have v4call cloned, open <code>public/nostr-gen.html</code> in any browser. It generates an npub + nsec entirely in the browser using <code>window.crypto.subtle</code>. The keys never touch a network.
:Save the npub (public, fine to share) and the nsec (private, NEVER share, treat like a posting key).

;Option B — Use a Nostr client you already use
:Damus, Amethyst, Iris, nos2x, Alby, etc. all let you export your npub. Settings → Profile → Public key.

;Option C — Command-line with <code>nak</code>
:Install [https://github.com/fiatjaf/nak nak]: <code>go install github.com/fiatjaf/nak@latest</code>
:Then run <code>nak key generate</code> to make a new pair.

'''⚠ Do this 3 times if you need 3 fresh pairs.''' Or use existing keys you already trust — the 3 don't have to be new.

Write down the 3 npubs in a notes file. Example:

npub1aaaa... (your daily key)
npub1bbbb... (a partner's key)
npub1cccc... (your v4call server's identity key)

== Step 2: Convert npub to hex ==

'''Important''': Nostr relays internally use the '''hex''' form of public keys, not the bech32 npub form. Same key, different encoding. <code>nostr-rs-relay</code>'s whitelist needs the hex.

;Easiest converter — nostr-gen.html
:If you generated keys via <code>nostr-gen.html</code>, the page already shows both forms. Copy the hex.

;Web converter
:[https://nostrcheck.me/converter/ nostrcheck.me/converter] — paste npub, get hex. (Use any reputable converter; the math is public.)

;Command-line
:With nak: <code>nak decode npub1aaaa...</code> — prints the hex pubkey.
:With Python: <code>pip install bech32</code>, then a 3-line script. (Out of scope here.)

You should end up with 3 hex strings, each 64 characters long (lowercase, 0-9 and a-f only). Example:

npub1aaaa... → abc123def456... (64 hex chars)
npub1bbbb... → fff789abc012... (64 hex chars)
npub1cccc... → 111aaa222bbb... (64 hex chars)

Save these. You will paste them into <code>config.toml</code> in Step 10.

'''💡 Tip''': If the converter spits out anything other than 64 hex chars, you pasted the wrong thing (probably an nsec — that's the private key, never paste it into a converter you don't fully trust). Double-check the input started with <code>npub1</code>, not <code>nsec1</code>.

== Step 3: Create Your Vultr VPS (x2) ==

You need '''two''' VPS boxes — one for each relay. Repeat this step twice. Name them differently (e.g. <code>nostr-hivebook</code> and <code>nostr-v4call</code>) so you don't confuse them later.

# Log into [https://my.vultr.com my.vultr.com]
# Click '''Deploy New Server'''
# Choose '''Cloud Compute — Shared CPU'''
# Choose a location close to where most of your readers are
# Choose '''Ubuntu 24.04 LTS x64'''
# Choose the '''$6/month''' plan (1 CPU, 1GB RAM, 25GB SSD) — plenty for a private relay with 3 publishers
# Set Server Hostname to something like <code>nostr-hivebook</code>
# Click '''Deploy Now'''

Wait ~60 seconds for it to start. Click the server to find:
* '''IP Address''' — looks like <code>123.456.789.012</code> — write it down
* '''Password''' — click the eye icon — write it down

Repeat for the second server. Now you should have:

nostr-hivebook → IP_A password_A
nostr-v4call → IP_B password_B

'''💡 Tip''': $6/month per relay is fine for low-traffic private relays. If your 3 keys post infrequently and the world reads occasionally, you'll never hit any limits. If you want to be cheap, $3.50/month boxes also work (512MB RAM) but pulls/builds are slower.

== Step 4: Point Your Domains at the VPS Boxes ==

Log into your DNS provider for each domain and add an '''A''' record:

;For <code>nostr.hive-book.com</code>
:{| class="wikitable"
|-
! Field !! Value
|-
| Type || A
|-
| Name || <code>nostr</code>
|-
| Value || IP_A (the hive-book VPS)
|-
| TTL || 300
|}

;For <code>nostr.v4call.com</code>
:Same setup, but Name = <code>nostr</code>, Value = IP_B (the v4call VPS).

DNS takes a few minutes to propagate. From your computer:

nslookup nostr.hive-book.com
nslookup nostr.v4call.com

Each must show the correct VPS IP before Step 13 (Caddy needs the DNS to resolve to fetch a certificate). You can continue with the other steps while waiting.

== Step 5: Log into Your VPS ==

Open a terminal:

ssh root@IP_A

Type <code>yes</code> at the fingerprint prompt, then paste the password from Vultr (right-click to paste in most terminals).

If Vultr forces a password change on first login, set a strong new one and write it down.

'''Repeat the rest of this guide on both boxes.''' We'll do them one at a time. Steps 6–14 are identical on both — only the domain name in Step 11 (Caddyfile) changes.

== Step 6: Update and Secure the Server ==

Always start with a system update:

apt update && apt upgrade -y

This may take a few minutes. If it asks about restarting services, hit Enter to accept defaults.

'''Optional but recommended — make a non-root user''' (you can skip if you're the only person ever touching this box and you trust your password):

adduser nostr
usermod -aG sudo nostr

Then later you can <code>ssh nostr@IP_A</code> and <code>sudo</code> for privileged commands. For this guide we'll just stay as root for simplicity — fine for a single-purpose box.

== Step 7: Install Docker ==

Install Docker the official way:

apt install -y ca-certificates curl
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" > /etc/apt/sources.list.d/docker.list
apt update
apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Verify:

docker --version
docker compose version

You should see version numbers for both. If not, re-run the apt install line.

'''💡 Tip''': <code>docker compose</code> (with a space) is the new way. The old <code>docker-compose</code> (with a hyphen) is deprecated. This guide uses the new form.

== Step 8: Open the Firewall ==

Vultr boxes start with no firewall, but it's good hygiene to enable one. We need ports 22 (SSH), 80 (HTTP, for Let's Encrypt), and 443 (HTTPS/WSS).

ufw allow 22/tcp
ufw allow 80/tcp
ufw allow 443/tcp
ufw --force enable
ufw status

You should see all three ports listed as ALLOW.

'''⚠ Important''': do NOT skip port 80. Caddy uses HTTP-01 ACME challenges to get the TLS certificate, which needs port 80 reachable from the internet. Closing it = no certificate = no <code>wss://</code>.

== Step 9: Create the Relay Project Folder ==

mkdir -p /opt/nostr-relay
cd /opt/nostr-relay
mkdir -p data caddy_data caddy_config

You'll create three files in <code>/opt/nostr-relay</code>:
* <code>config.toml</code> — relay configuration (whitelist lives here)
* <code>Caddyfile</code> — TLS reverse proxy config (domain name lives here)
* <code>docker-compose.yml</code> — orchestration

== Step 10: Write the Relay Config (config.toml) ==

We'll use [https://github.com/scsibug/nostr-rs-relay nostr-rs-relay] — a battle-tested Rust relay with a simple TOML config and a built-in pubkey whitelist (no plugins, no extra daemon).

Create the config file:

nano /opt/nostr-relay/config.toml

Paste this — '''replace the three hex strings''' in <code>pubkey_whitelist</code> with the 3 hex pubkeys from Step 2:


<pre>
[info]
relay_url = "wss://nostr.hive-book.com/"
name = "hive-book private relay"
description = "Private write-whitelisted relay. Public read."
# pubkey of the relay operator (hex). Optional but nice.
# pubkey = "your-operator-hex-pubkey"
# contact = "mailto:you@example.com"

[database]
data_directory = "/usr/src/app/db"

[network]
# Bind inside the container; Caddy will reverse-proxy from the public 443.
address = "0.0.0.0"
port = 8080

[limits]
messages_per_sec = 10
subscriptions_per_min = 30
max_event_bytes = 131072 # 128 KB per event — plenty for normal Nostr use
max_ws_message_bytes = 131072
max_ws_frame_bytes = 131072
broadcast_buffer = 1024
event_persist_buffer = 16

[authorization]
# ONLY these hex pubkeys can publish (write) events.
# Reading is open to anyone in the world.
pubkey_whitelist = [
"REPLACE_WITH_HEX_OF_NPUB_1",
"REPLACE_WITH_HEX_OF_NPUB_2",
"REPLACE_WITH_HEX_OF_NPUB_3",
]

[verified_users]
mode = "disabled"

[retention]
# Keep everything forever for a private relay. Tweak if you want.
# max_events = 0
# max_bytes = 0
</pre>
Save with <code>Ctrl+O</code>, Enter, then <code>Ctrl+X</code> to exit nano.

'''⚠ Important — read this twice, it's the #1 mistake''':
* '''The whitelist is the HEX form of the pubkey, NEVER the npub form.''' Lowercase, exactly 64 characters, only digits 0-9 and letters a-f. Pasting <code>npub1abc...</code> values here is a silent disaster — the relay starts fine and accepts connections fine, but every single EVENT you publish gets rejected with <code>OK accepted=false reason="blocked: pubkey is not allowed to publish to this relay"</code>, because no pubkey in the world will ever match those bech32 strings. You won't see this until you try to publish, and even then it's a confusing error that looks like ''you'' did something wrong.
* '''If you skipped Step 2, go back and do it now.''' Step 2 is specifically about converting npub → hex for this exact purpose. The conversion is deterministic — same key, just different encoding. <code>nak decode npub1...</code> on your laptop prints the hex; or use <code>nostr-gen.html</code> in the v4call repo (the public hex pubkey is shown right under the npub, with a copy button).
* '''Sanity check before saving''': every entry between the quotes should be exactly 64 characters, all lowercase, all hex. Count if you have to. <code>npub1...</code> values are roughly 63 characters and contain non-hex letters like <code>z</code>, <code>p</code>, <code>j</code> — instant red flag.
* '''If you typo a hex character (63 chars, or a stray <code>g</code>-<code>z</code>), the relay refuses to start.''' Check <code>docker compose logs nostr-relay</code> for the parse error. ''But pasting valid-looking npubs starts cleanly and silently rejects every publish'' — that's the bigger trap.
* '''For the second server, change <code>relay_url</code> and <code>name</code> to the v4call values, but the whitelist stays the same.'''

'''💡 Tip''': nostr-rs-relay also supports paid-relay mode and NIP-42 AUTH gating. For "just whitelist 3 keys", <code>pubkey_whitelist</code> is the simplest mechanism. The relay will reject any incoming EVENT whose <code>pubkey</code> field isn't in this list, with a clear NOTICE back to the client.

== Step 11: Write the Caddy Config (Caddyfile) ==

[https://caddyserver.com Caddy] is a reverse proxy that auto-fetches and auto-renews Let's Encrypt certificates. It's much simpler than nginx + certbot for a single-purpose box.

Create the Caddyfile — '''use the correct domain for this server''' (hive-book.com on the first box, v4call.com on the second):

nano /opt/nostr-relay/Caddyfile

Paste (for the first server):
<pre>
nostr.hive-book.com {
# WebSocket reverse proxy to the relay container on port 8080.
reverse_proxy nostr-relay:8080

# Friendly response if someone hits the URL in a normal browser.
@browser {
not header Connection *Upgrade*
not path /
}

# Optional: log access. Comment out to disable.
log {
output file /data/access.log
format console
}
}
</pre>
Save and exit.

For the second box, the only change is the first line:

nostr.v4call.com {
reverse_proxy nostr-relay:8080
...
}

Caddy will see this file, fetch a Let's Encrypt cert for the domain on first start, and auto-renew it forever. Zero manual cert work.

'''💡 Tip''': Caddy stores its cert state in <code>/data</code> inside the container — we mount that to <code>./caddy_data</code> on the host so the cert survives container restarts. Don't delete that folder unless you want Caddy to re-issue from scratch.

== Step 12: Write the docker-compose.yml ==

nano /opt/nostr-relay/docker-compose.yml

Paste:
<pre>
services:
nostr-relay:
image: scsibug/nostr-rs-relay:latest
container_name: nostr-relay
restart: unless-stopped
volumes:
- ./config.toml:/usr/src/app/config.toml:ro
- ./data:/usr/src/app/db
expose:
- "8080"
networks:
- relaynet

caddy:
image: caddy:2-alpine
container_name: caddy
restart: unless-stopped
ports:
- "80:80"
- "443:443"
volumes:
- ./Caddyfile:/etc/caddy/Caddyfile:ro
- ./caddy_data:/data
- ./caddy_config:/config
depends_on:
- nostr-relay
networks:
- relaynet

networks:
relaynet:
driver: bridge
</pre>
Save and exit.

What this does:
* '''nostr-relay''' container runs the Rust relay, reads <code>config.toml</code>, persists its SQLite DB to <code>./data</code> on the host. Not exposed to the public — only Caddy talks to it on the internal Docker network.
* '''caddy''' container holds the public ports (80, 443), terminates TLS, and reverse-proxies WebSocket traffic to the relay. Persists certificates to <code>./caddy_data</code>.

== Step 13: Start It Up ==

From <code>/opt/nostr-relay</code>:

docker compose pull
docker compose up -d

Watch the logs for a minute:

docker compose logs -f

You should see:
* nostr-relay: <code>relay starting on 0.0.0.0:8080</code> (or similar)
* caddy: a line about obtaining a certificate for <code>nostr.hive-book.com</code> via the ACME challenge, then a successful <code>certificate obtained</code> line.

Press <code>Ctrl+C</code> to stop tailing logs. The containers keep running.

'''⚠ If you see <code>ERROR r2d2: unable to open database file: /usr/src/app/db/nostr.db</code>''' (looping every few seconds in the <code>nostr-relay</code> logs):

This is the most common first-run snag. The <code>scsibug/nostr-rs-relay</code> container runs as a non-root user (UID 100) inside the container, but your <code>./data</code> directory on the host was created by <code>root</code> in Step 9 — so the container user can't write to it. SQLite refuses to create the DB file, the relay loops, and Caddy proxies start returning 502.

'''Quick fix (just unblock me)''' — works on any image, any version, fine for a single-purpose box where the data dir holds only public Nostr events:

cd /opt/nostr-relay
docker compose down
chmod -R 777 /opt/nostr-relay/data
docker compose up -d
docker compose logs -f nostr-relay

You should now see:

INFO nostr_rs_relay::repo::sqlite: Built a connection pool "writer" (min=0, max=2)
INFO nostr_rs_relay::repo::sqlite: Built a connection pool "reader" (min=0, max=8)

…and '''no more''' <code>r2d2: unable to open database file</code> errors. Press <code>Ctrl+C</code> to stop tailing.

'''Tighter fix (chown to the correct UID)''' — recommended once you've confirmed the relay works. The image uses an <code>appuser</code> created by the base image, but the exact UID can change between image releases — '''don't trust a hardcoded number from a guide, ask the image''':

# Find out what UID the container actually runs as:
docker run --rm scsibug/nostr-rs-relay:latest id
# Example output: uid=1000(appuser) gid=1000(appuser) groups=1000(appuser)

Take the UID and GID from that output (let's say both are 1000) and apply them to the data directory:

cd /opt/nostr-relay
docker compose down
chmod -R 755 /opt/nostr-relay/data # back to sensible perms
chown -R 1000:1000 /opt/nostr-relay/data # use YOUR numbers from above
docker compose up -d
docker compose logs -f nostr-relay

If logs are clean, the chown stuck and you're now running with proper UID alignment instead of world-writable.

'''💡 Why does this happen?''' The relay's image creates a non-root <code>appuser</code> and switches to it before running — good security hygiene (the container can't run as root even if exploited). The cost is that any host-mounted volume needs to be writable by ''that exact UID''. The host's <code>./data</code> folder was created by <code>root</code> in Step 9, so by default the container user can't write to it. Same pattern v4call uses (UID 1000 there) — Docker bind-mounts always need host-side permissions matching the container-side user.

'''💡 Will this break on image updates?''' Usually not — the UID is baked into the image and stays stable across patch releases. But if you ever <code>docker compose pull</code> a new image and the relay starts erroring on the DB again, re-run <code>docker run --rm scsibug/nostr-rs-relay:latest id</code> to check whether the UID changed, and re-chown if it did.

'''💡 Why not just always use <code>chmod 777</code>?''' For a private 3-key relay storing public events, it's genuinely fine — the data is signed-and-public by design and the box is single-purpose. The <code>chown</code> approach is just hygiene that pays off if the box ever ends up serving more than one thing.

'''💡 Ignore the <code>502</code> lines from random IPs''' (e.g. <code>monitor-telegram-clone-realtime/1.0</code>, IPs you don't recognise). Within minutes of a fresh domain getting a Let's Encrypt cert, internet-wide scanners hit it. They get a 502 while the relay is broken and a normal HTTP response (or WebSocket upgrade) once it's working. Not an attack, not anything to fix — just background noise of the public internet. <code>ufw</code> + the whitelist + Caddy's TLS handshake are doing their jobs.

'''⚠ If Caddy can't get a certificate''':
* DNS for the domain isn't pointing to this VPS yet → wait, run <code>nslookup nostr.hive-book.com</code> from a different machine, confirm it resolves to your IP.
* Port 80 is closed → re-check Step 8.
* Caddy logs will tell you the exact ACME failure reason. Read them.

== Step 14: Test the Relay ==

;Test 1 — Is the WebSocket reachable?
:You need a tiny WebSocket client on your laptop. Pick whichever is easiest for your OS:

;'''Option 1A — websocat prebuilt binary (any Linux, no compilation)'''
:Skip <code>cargo install websocat</code> on Ubuntu 24.04 — its apt-shipped Rust 1.75 is too old to compile current websocat, and you'll waste 10 minutes downloading half of crates.io before hitting an <code>edition2024</code> error. Grab the prebuilt static binary instead:
: <code>sudo wget -O /usr/local/bin/websocat https://github.com/vi/websocat/releases/latest/download/websocat.x86_64-unknown-linux-musl</code>
: <code>sudo chmod +x /usr/local/bin/websocat</code>
: <code>websocat --version</code>

;'''Option 1B — wscat (Node.js, simpler if you already have npm)'''
: <code>sudo apt install -y npm && sudo npm install -g wscat</code>
:Then use <code>wscat -c wss://...</code> instead of <code>websocat wss://...</code> in the steps below. wscat prints a "Connected" banner so it's friendlier than websocat for first-time testing.

;'''Option 1C — nak (Go, the Nostr-native option, also handy for Steps 1 + 2)'''
:Install Go from apt and use it to build nak:
: <code>sudo apt install -y golang-go</code>
: <code>go install github.com/fiatjaf/nak@latest</code>
: <code>echo 'export PATH=$PATH:$HOME/go/bin' >> ~/.bashrc && source ~/.bashrc</code>
: <code>nak --help</code> # confirm it's on PATH
:Then skip websocat/wscat entirely:
: <code>nak req -k 1 wss://nostr.hive-book.com</code>
:Prints any matching events and exits. Done. nak also does npub/hex conversion (<code>nak decode npub1...</code>) and signing (<code>nak event --sec ...</code>) — see Step 1 and the bonus test at the end of Step 14.
:'''💡 Tip''': if <code>nak --help</code> says "command not found" after install, your shell hasn't reloaded PATH. Either open a new terminal or run <code>export PATH=$PATH:$HOME/go/bin</code> in the current one.

;'''Option 1D — Mac users'''
: <code>brew install websocat</code> just works.

Once you have one of the above, connect:

websocat -v wss://nostr.hive-book.com/
# or: wscat -c wss://nostr.hive-book.com/

'''⚠ websocat's silent connection trips up first-time users.''' Without the <code>-v</code> flag, websocat opens the WebSocket and just sits there with a blank cursor — no "Connected!" banner, no prompt, nothing. That's '''not''' a hang, that's a working connection waiting for you to type. The <code>-v</code> flag in the command above prints lifecycle messages like <code>get_ws_client_peer</code> so you can see it actually connected. (wscat is friendlier — it prints "Connected (press CTRL+C to quit)".)

Once connected (silent or banner, doesn't matter), paste this exact line:

["REQ","test",{"kinds":[1],"limit":1}]

Press Enter. The relay will respond with <code>["EOSE","test"]</code> (end of stored events) — meaning it's alive and there's nothing stored yet. Press <code>Ctrl+C</code> to disconnect.

'''💡 If you got nothing back''' after typing the REQ — there's actually a stored event somewhere on this relay (so the response would be a JSON event line then EOSE), or the relay is alive but rejecting your REQ for some reason. Run with <code>nak req -k 1 wss://...</code> instead to get a clearer view of what's happening. Or check <code>docker compose logs nostr-relay</code> on the server side for what it received.

'''💡 <code>["NOTICE","could not parse command"]</code> is also a "working" signal.''' If you accidentally hit Enter on a blank line, type plain English, or paste anything that isn't valid Nostr JSON, the relay replies with a NOTICE rejection. That's '''good news''' — it proves the relay parsed your input and pushed back. A truly broken relay would either disconnect or stay silent. So if you mistype the REQ command and see a NOTICE come back, just paste the correct JSON and try again.

'''💡 You don't actually have to type anything to confirm Test 1 passed.''' The verbose output from <code>websocat -v</code> already tells you everything you need:

[INFO websocat::net_peer] Connected to TCP <vps-ip>:443
[INFO websocat::ws_client_peer] Connected to ws, response headers: Headers { ...
Server: Caddy
Upgrade: websocket
}

The TCP-on-443 line + the <code>Upgrade: websocket</code> header + <code>Server: Caddy</code> together prove: DNS resolved, TLS handshake completed, Caddy accepted the connection, the WebSocket upgrade succeeded, the relay is on the other end. If you see those, you can <code>Ctrl+C</code> right there — Test 1 is already a pass. Typing the REQ is just an extra "and it speaks Nostr" sanity check on top.

'''💡 Tip''': you can also test purely from a browser. Open your client of choice (e.g. [https://nostrudel.ninja nostrudel.ninja]) and add <code>wss://nostr.hive-book.com</code> as a custom relay. If it connects without TLS errors, the relay is reachable. The browser console (F12) will show the WebSocket open/close lifecycle.

;Test 2 — Whitelist actually rejects strangers
:From any Nostr client logged in with a key that is '''NOT''' in your whitelist, try posting a note and add <code>wss://nostr.hive-book.com/</code> as a relay. The relay should respond with an OK=false NOTICE explaining the pubkey isn't allowed. Look at <code>docker compose logs nostr-relay</code> — you'll see the rejection logged.

;Test 3 — Whitelisted key CAN publish
:Use a Nostr client logged in with one of your 3 whitelisted keys. Add the relay. Post a short note. Run Test 1's REQ command again — this time you should see the event come back.

If all three tests pass, your first relay is live. 🎉

;Bonus test with <code>nak</code>
:If you have nak installed, you can publish straight from the command line:
: <code>nak event --sec YOUR_NSEC_HEX -c "hello private relay" wss://nostr.hive-book.com</code>
:And query:
: <code>nak req -k 1 wss://nostr.hive-book.com</code>

== Step 15: Repeat for the Second Server ==

Log out, ssh into the v4call box (<code>ssh root@IP_B</code>), and repeat Steps 6 through 14 with these tweaks:

* Step 10 — <code>relay_url</code> and <code>name</code> in <code>config.toml</code> use the v4call domain.
* Step 11 — first line of the Caddyfile is <code>nostr.v4call.com {</code>.

The 3-key whitelist stays identical on both boxes — that's the whole point: same 3 keys can publish to either relay, and you have geographic / provider redundancy in case one box has an issue.

When you're done, both <code>wss://nostr.hive-book.com</code> and <code>wss://nostr.v4call.com</code> answer to the same 3 keys.

== Updating the Whitelist ==

To add or remove a key:

# SSH into the box.
# <code>nano /opt/nostr-relay/config.toml</code> and edit the <code>pubkey_whitelist</code> array.
# <code>cd /opt/nostr-relay && docker compose restart nostr-relay</code>

The relay restarts in a couple of seconds. Caddy keeps running — no certificate work needed for a config tweak.

Repeat on the second box if you want both relays in sync.

'''💡 Tip''': make this a habit — keep the 3 hex pubkeys in a notes file outside the server too. When you rotate a key, update the notes file ''and'' both relays.

== Common Problems and Fixes ==

;'''Caddy: "no domains qualify for managed certificates"'''
:DNS not pointing to the box yet, or pointing to the ''wrong'' box. Run <code>nslookup yourdomain</code> from a third location. If it shows the wrong IP, fix DNS and wait 5 minutes.

;'''Caddy: "context deadline exceeded" / "connection refused" on ACME challenge'''
:Port 80 is firewalled. Re-check <code>ufw status</code>. Also make sure no other process is on port 80 (<code>ss -tlnp | grep ':80'</code>).

;'''Relay logs: "invalid pubkey in whitelist"'''
:Your hex string isn't 64 lowercase hex characters. Common mistake: pasting the npub instead of the hex; or leaving in a stray space; or accidentally pasting an nsec. Reconvert from npub → hex (Step 2) and paste again.

;'''Every publish gets <code>OK accepted=false reason="blocked: pubkey is not allowed to publish to this relay"</code> even though I added my key'''
:'''99% of the time''': you pasted <code>npub1...</code> values into <code>pubkey_whitelist</code> instead of the 64-char hex form. The relay starts cleanly with npubs (it's just a string list to TOML) but ''no'' real pubkey ever matches a bech32 string, so every publish silently rejects.
:Fix: convert each npub to hex on your laptop —
: <code>nak decode npub1abc... | jq -r .pubkey</code>
:or open <code>nostr-gen.html</code> from the v4call repo (the hex pubkey is now displayed under the npub with a copy button). Replace every entry in <code>pubkey_whitelist</code> with the hex form, then:
: <code>cd /opt/nostr-relay && docker compose restart nostr-relay</code>
:Watch <code>docker compose logs -f nostr-relay</code> while you re-publish from your client — the rejection line shows exactly which hex pubkey the relay is checking against; you can compare it character-by-character to <code>config.toml</code>. If they don't match, the wrong key got loaded into your client (or the wrong hex into the config).
:Edge cases that cause the same error: case mismatch (whitelist must be lowercase), a stray trailing space inside the quotes, or you edited <code>config.toml</code> on one box but not the other. Always check both.

;'''Whitelisted client gets rejected anyway'''
:Almost always: the client signed the event with a different key than you put on the whitelist (e.g. you converted the wrong npub, or you have multiple identities in your client). In the client, verify which key is actively signing, get its npub, convert again, compare to <code>config.toml</code>.

;'''<code>websocat wss://...</code> says "TLS handshake error"'''
:Caddy hasn't finished provisioning the certificate yet. Wait 30 seconds and try again. If it persists for >5 minutes, check <code>docker compose logs caddy</code>.

;'''<code>cargo install websocat</code> fails with <code>feature 'edition2024' is required</code>'''
:Ubuntu 24.04's apt cargo (1.75) is too old to compile current websocat. Don't try to upgrade Rust just for this — grab the prebuilt static binary instead (Test 1, Option 1A in Step 14). Or use <code>wscat</code> via npm. Or skip ahead to <code>nak</code>.

;'''<code>websocat: command not found</code> after a failed install'''
:The cargo install errored before it could place the binary. Use Option 1A (prebuilt binary to <code>/usr/local/bin</code>) instead.

;'''<code>r2d2: unable to open database file</code> looping in nostr-relay logs (and Caddy returning 502)'''
:UID mismatch on the bind-mounted data directory. The container runs as a non-root <code>appuser</code>; your <code>./data</code> folder is owned by root. Quick fix: <code>docker compose down && chmod -R 777 /opt/nostr-relay/data && docker compose up -d</code> (fine for a single-purpose box). Tighter fix: find the image's actual UID via <code>docker run --rm scsibug/nostr-rs-relay:latest id</code>, then <code>chown -R UID:GID /opt/nostr-relay/data</code>. See the inline note at the end of Step 13 for the full explanation.

;'''Container keeps restarting'''
:<code>docker compose logs --tail=50 nostr-relay</code> — almost always a config.toml syntax error (missing quote, unclosed bracket). Fix and <code>docker compose up -d</code>.

;'''Disk filling up over time'''
:Check <code>du -sh /opt/nostr-relay/data</code>. If you're storing kind 1 notes from 3 active users and never deleting, it grows slowly (megabytes per year). If it grows fast, something is wrong (a whitelisted key is firehosing) — investigate the events table.

== Tips for Nostr Noobs ==

* '''npub vs nsec''': npub starts with <code>npub1</code>, is your public identity, share freely. nsec starts with <code>nsec1</code>, is your private signing key, '''never paste it anywhere except your own client''' (and ideally only via a hardware-isolated tool like a browser extension or a hardware signer). If you ever paste an nsec into a website you don't fully trust, treat that key as compromised and rotate.
* '''There is no "delete" on Nostr''' — events are signed objects relays store. NIP-09 has a "delete request" event, but relays may or may not honour it, and other relays will still have copies. Treat anything you publish as permanent.
* '''Public read, private write is a useful pattern''' — what you've built. People can ''see'' what your 3 keys publish (great for credibility, transparency, archive value) but can't pollute your relay with their own stuff.
* '''Federation note for v4call operators''': the v4call NOSTR-DESIGN-NOTES.md (in the v4call repo) describes a server-level identity (per-server keypair + <code>kind:30078</code> announce events). One natural pattern: the third whitelisted key on your relay is your v4call ''server's'' Nostr identity, while the other two are your personal + a partner's. The relay then doubles as v4call federation discovery infrastructure.
* '''Backups''': back up <code>/opt/nostr-relay/data</code> (the SQLite DB). The Caddy cert volume can be re-issued from Let's Encrypt at any time, so it's less critical, but no harm in including it.
* '''Costs''': $6/month per Vultr box × 2 = $12/month. Domain renewal is the only other cost. No platform fees, no per-event charges.
* '''Want to learn more?''' Read [https://github.com/nostr-protocol/nips the NIPs] (Nostr Implementation Possibilities) — they're short, readable specs. NIP-01 is the protocol core. NIP-11 is relay information documents (worth implementing later via <code>relay_info</code> in config.toml). NIP-42 is AUTH (a more sophisticated alternative to a flat whitelist).
* '''Test client''': [https://nostrudel.ninja nostrudel.ninja] is a clean web client that lets you add custom relays per account. Great for poking at your own relay without committing to a heavy app.

You now have two private, whitelisted Nostr relays. Welcome to running your own Nostr infrastructure. 🌿

Hive Blockchain Create Custom Coins

2026-05-08T09:37:22Z

AwesomO:

{{:LICENCE_HEADER_CC0}}
= v4call — How to Create Your Own Custom Token (e.g. CNOOBS) on Hive Engine =
From CompleteNoobs
F
This guide walks you through creating a custom Hive Engine token (example: '''CNOOBS''') in under 10 minutes. No coding required.

These tokens power the custom communication economy in v4call: you can set rates like "1 CNOOBS = 1 text message" or "10 CNOOBS = 1 hour video call", gift them to friends/family, or let blocked users bypass your blocklist if they hold enough of your token.

'''Why create your own token?'''
* Full control over supply and distribution.
* Real utility inside v4call (and any other Hive dApp that supports Hive Engine tokens).
* Scarcity you decide — perfect for personal or community communication economies.
* Transferable, tradable, and giftable via Hive Keychain or TribalDex.

'''Cost''': Approximately 100 BEE (Hive Engine's utility token). BEE price fluctuates — check current value on TribalDex or PeakD. This is a one-time creation fee.

'''Source''': Based on the official Hive Engine / TribalDex interface (as of 2026).

'''End result''': A live custom token (e.g. CNOOBS) that appears in users' Hive Keychain wallets and can be used in your v4call rates post.

== Contents ==
* [[#What_You_Need|1 What You Need]]
* [[#Step_1:_Get_Some_BEE_Tokens|2 Step 1: Get Some BEE Tokens]]
* [[#Step_2:_Log_In_to_TribalDex|3 Step 2: Log In to TribalDex]]
* [[#Step_3:_Create_Your_Token|4 Step 3: Create Your Token]]
* [[#Step_4:_Issue_Tokens_to_Yourself|5 Step 4: Issue Tokens to Yourself]]
* [[#Step_5:_Optional_-_Add_Metadata_(Logo_Description)|6 Step 5: Optional - Add Metadata (Logo & Description)]]
* [[#Step_6:_Distribute_Your_Tokens|7 Step 6: Distribute Your Tokens]]
* [[#Using_Your_Token_in_v4call|8 Using Your Token in v4call]]
* [[#Common_Problems_and_Fixes|9 Common Problems and Fixes]]
* [[#Quick_Reference|10 Quick Reference]]

== What You Need ==
* A Hive account (e.g. @noblemage) with Hive Keychain installed and the '''active key''' available.
* Some BEE tokens (≈100 BEE for creation fee).
* A web browser.

You do '''not''' need to run a node or write code.

== Step 1: Get Some BEE Tokens ==
BEE is the "gas" token for Hive Engine actions.

# Go to [https://tribaldex.com tribaldex.com] or any Hive Engine market (e.g. via PeakD wallet).
# Swap or buy BEE using HIVE or HBD (very easy with Keychain).
# Alternative: Many users get small amounts of BEE from community airdrops or by swapping on the built-in market.

Make sure you have at least 110 BEE to cover the fee plus a small buffer.

== Step 2: Log In to TribalDex ==
# Visit [https://tribaldex.com/tokens/create https://tribaldex.com/tokens/create]
# Click the login button at the top.
# Hive Keychain will pop up — approve the login with your '''active key''' (or posting key in some cases, but active is safest for token actions).

You are now logged in as your Hive account.

== Step 3: Create Your Token ==
On the token creation form, fill in the following fields carefully. Most cannot be changed later.

* '''Symbol''' — e.g. '''CNOOBS''' (uppercase, 1–10 characters, unique)
* '''Name''' — e.g. '''Cnoobs Coins'''
* '''Max Supply''' — Choose a number (e.g. 1,000,000). This is the absolute maximum that can ever exist. You can issue less.
* '''Precision''' — Usually '''3''' (allows 0.001 precision). You can only increase this later, not decrease.
* '''Website''' (optional) — Link to your profile or v4call server (e.g. https://call.yourdomain.com)
* '''Description''' (optional) — Short text like "Personal communication token for v4call — used for messages and calls with @cnoobz"

Double-check everything — the symbol especially cannot be changed.

Click '''Create Token'''.

Hive Keychain will ask you to approve a custom_json transaction. Confirm it.

Wait 3–10 seconds for confirmation on the blockchain.

Success message should appear: your token is now created!

== Step 4: Issue Tokens to Yourself ==
After creation, you usually start with zero balance.

# Go to [https://tribaldex.com/tokens/manage https://tribaldex.com/tokens/manage]
# Find your new token (CNOOBS) in the list.
# Click the '''Issue''' button.
# Enter the amount you want to issue to yourself (e.g. 10000).
# Confirm with Keychain.

You now hold the full issued supply.

== Step 5: Optional — Add Metadata (Logo & Description) ==
# Still on the manage page, click the edit icon for your token.
# Upload a square logo image (recommended 200x200 px or larger).
# Improve the description and website link.
# Save changes (another small Keychain transaction).

This makes your token look professional when users view it in wallets or markets.

== Step 6: Distribute Your Tokens ==
* Send to friends/family via Keychain → "Tokens" tab → Transfer.
* Airdrop to your community.
* Use in v4call rates (see below).
* List on TribalDex market if you want people to buy/sell them.

Tokens are fully transferable and appear instantly in recipients' Hive Keychain wallets.

== Using Your Token in v4call ==
Once you have your token:

# Go to your v4call server → /rate-editor.html
# In the rate editor (V2 format), create a new list like [LIST:token-holders]
# Set TOKEN:CNOOBS
# Define rates, e.g.:
** TEXT:1 CNOOBS
** VOICE:RING:5 CNOOBS;CONNECT:10 CNOOBS;RATE:20 CNOOBS/hr
* Your server will automatically verify balances using public Hive Engine RPC when someone tries to call or message you.

Blocked users can bypass your blocklist if you set ALLOW-IF-TOKEN:CNOOBS and they hold enough.

== Exchanging tokens on an exchange ==
Its pretty simple - you can exchange with hive-engine.com
* https://hive-engine.com/trade/CNOOBS
<code>https://hive-engine.com/trade/<YOUR_TOKEN></code>

== Common Problems and Fixes ==
=== "Not enough BEE" error ===
Buy or swap more BEE on TribalDex.

=== Token symbol already taken ===
Choose a different symbol (add numbers or make it longer, e.g. CNOOBS2).

=== Transaction fails ===
Make sure you are using the '''active key''' in Keychain for token creation/issuing. Restart Keychain if needed.

=== Can't find my token after creation ===
Refresh the page or check https://hive-engine.com/tokens — it may take a few seconds to appear.

=== Want to issue more later? ===
You can issue up to your max supply at any time from the manage page.

== Quick Reference ==
{| class="wikitable"
|-
! Action !! Where to Do It
|-
| Create token || https://tribaldex.com/tokens/create
|-
| Manage / Issue tokens || https://tribaldex.com/tokens/manage
|-
| View all tokens || https://hive-engine.com/tokens
|-
| Swap BEE || TribalDex market
|-
| Check balance in Keychain || Hive Keychain extension → Tokens tab
|}

'''Next step for v4call users''': After creating your token, update your v4call-rates post using the improved rate-editor.html to include your custom token rates and blocklist bypass.

You now have your own personal communication currency on Hive!

== Staking <b>UNTESTED</b> at current time ==
== Appendix A: Enabling Staking on an Existing Token (e.g. CNOOBS) ==
So you've created your token but forgot to enable staking? No problem — staking can be enabled on an existing Hive Engine token at any time. This appendix walks you through it.

'''Why enable staking?'''
* Lets holders "lock up" tokens for influence, rewards, or governance.
* Required if you ever want to add a reward pool (Scotbot/SMT) later — staking is a prerequisite.
* Useful in v4call: you can require holders to ''stake'' (not just hold) CNOOBS to bypass blocklists or unlock premium rates. Staked tokens can't be quickly dumped, so they prove genuine commitment.
* Adds scarcity — staked tokens are removed from the liquid circulating supply.

'''Cost''': Approximately '''1000 BEE''' (one-time burn fee). This is significantly more than the 100 BEE token creation fee, so make sure you actually want this feature before paying. The fee is non-refundable.

'''Important''': Enabling staking is generally a one-way action. Once enabled it cannot be disabled. Some parameters (like cooldown period) can be edited later, but the staking feature itself is permanent. Plan your tokenomics before pulling the trigger.

=== What You Need ===
* Your existing token (e.g. CNOOBS) created on Hive Engine.
* Your Hive account with Hive Keychain and the '''active key''' available.
* At least '''1010 BEE''' in your wallet (1000 for the fee + small buffer).
* A few minutes.

=== Step A1: Get 1000+ BEE ===
Same as before — swap HIVE/HBD for BEE on [https://tribaldex.com tribaldex.com] or buy BEE on the Hive Engine market. Make sure you have at least 1010 BEE liquid in your wallet (not staked) before continuing.

=== Step A2: Go to the Manage Tokens Page ===
# Visit [https://tribaldex.com/tokens/manage https://tribaldex.com/tokens/manage]
# Log in with Hive Keychain (active key) if not already logged in.
# Find your token (CNOOBS) in the list of tokens you own.

=== Step A3: Click "Enable Staking" ===
# Next to your token, look for the '''Enable Staking''' button or icon (sometimes shown as a lock/coin symbol). Depending on UI updates, it may be under an "Actions" or "More" menu.
# A form will appear with the following fields:

* '''Unstaking Cooldown (days)''' — How long it takes to unstake tokens once a holder requests it. Common values: 7, 14, 28, or 30 days. Longer = more commitment = more scarcity. For a personal communication token like CNOOBS, '''7 days''' is a reasonable starting point.
* '''Number of Transactions''' — How many payouts the unstake is split into. Example: 28 days over 4 transactions = the holder gets 25% of their unstaked tokens every 7 days. Common values: 1, 4, or matching the cooldown days.
* '''Enable Delegation''' (optional checkbox) — Lets users delegate (lend) staked tokens to others without unstaking. Highly recommended for v4call use cases (e.g. delegate CNOOBS to a friend so they can call you).
* '''Delegation Cooldown (days)''' (if delegation enabled) — How long after un-delegating before tokens return to the original staker. Usually 7 days.

'''Recommended starter settings for CNOOBS:'''
{| class="wikitable"
|-
! Field !! Suggested Value
|-
| Unstaking Cooldown || 7 days
|-
| Number of Transactions || 4 (= 25% every ~1.75 days)
|-
| Enable Delegation || Yes (checked)
|-
| Delegation Cooldown || 7 days
|}

# Double-check your settings — cooldown values can usually be edited later, but it costs additional small fees and confusion for holders.
# Click '''Enable Staking''' (or similar confirmation button).
# Hive Keychain will pop up asking you to approve a custom_json transaction that '''burns 1000 BEE'''. Confirm with your active key.
# Wait 3–10 seconds for blockchain confirmation.

Success! Staking is now live on your token.

=== Step A4: Verify Staking is Enabled ===
# Go to https://hive-engine.com/tokens
# Search for CNOOBS.
# Click the token — you should now see a "Stake" / "Unstake" / "Delegate" option visible to all holders.
# In your own Hive Keychain wallet, on the Tokens tab, CNOOBS should now show a small lock/stake icon next to the transfer button.

Try staking 10 CNOOBS yourself as a test — it should appear under "Staked Balance" immediately.

=== Step A5: Update v4call to Recognise Staked Tokens ===
Your v4call rate editor can distinguish between '''liquid''' and '''staked''' balances. Examples in V2 format:

[LIST:liquid-holders]
TOKEN:CNOOBS
TYPE:LIQUID
TEXT:1 CNOOBS

[LIST:committed-holders]
TOKEN:CNOOBS
TYPE:STAKED
MIN:100
TEXT:FREE
VOICE:FREE
ALLOW-IF-STAKED:CNOOBS:100

This means: anyone holding 100+ '''staked''' CNOOBS gets free messaging and bypasses the blocklist, while liquid holders pay normal rates. Staking proves long-term commitment, not just speculation.

=== Common Problems and Fixes (Staking) ===

==== "Insufficient BEE balance" ====
You need 1000+ BEE liquid (not staked). Buy/swap more on TribalDex.

==== "Enable Staking" button doesn't appear ====
* Make sure you're logged in as the token issuer (the account that created CNOOBS).
* Try a different Hive Engine RPC node — go to TribalDex settings and switch to a different node. Some nodes lag.
* Refresh and try again.

==== Transaction succeeds but staking doesn't activate ====
Wait 30–60 seconds and refresh — Hive Engine sometimes takes a moment to propagate. Check https://hive-engine.com/tokens to confirm.

==== Can I disable staking later? ====
Generally no — staking is a permanent feature once enabled. You ''can'' edit the cooldown period and delegation settings later (small Keychain transaction, no big fee), but the staking system itself stays on.

==== Can I add a reward pool now? ====
Yes — with staking enabled, you can now optionally pay another 1000 BEE for Scotbot/SMT to enable post curation rewards in CNOOBS. Not required for v4call use, but available if you want to grow a community around the token.

=== Updated Quick Reference ===
{| class="wikitable"
|-
! Action !! Cost (BEE) !! Where
|-
| Create token || 100 || tribaldex.com/tokens/create
|-
| Issue tokens || Free (gas only) || tribaldex.com/tokens/manage
|-
| '''Enable staking''' || '''1000''' || '''tribaldex.com/tokens/manage'''
|-
| Edit staking cooldown || ~Free (small fee) || tribaldex.com/tokens/manage
|-
| Enable Scotbot rewards (optional) || 1000 || tribaldex.com/smt/manage
|-
| View token info || Free || hive-engine.com/tokens
|}

'''Total cost so far for a staking-enabled CNOOBS''': ~1100 BEE (100 create + 1000 staking).

You now have a fully stakeable communication token — perfect for distinguishing committed v4call users from casual holders.

[[Category:Hive]]
[[Category:Hive Engine]]
[[Category:v4call]]
[[Category:Token Creation]]
[[Category:Web3]]

Hive Blockchain Create Custom Coins

2026-05-08T09:30:43Z

AwesomO: /* Selling tokens on an exchange */

Hive Blockchain Create Custom Coins

2026-05-08T09:30:25Z

AwesomO: /* Using Your Token in v4call */

Hive Blockchain -How to buy SWAP.BTC

2026-05-04T18:02:17Z

AwesomO: Created page with "= Swapping HIVE / HBD to SWAP.BTC (and back again) = ''A complete noobs walk-through to converting your Hive tokens into pegged Bitcoin (SWAP.BTC) on Hive-Engine, and then converting them back to HIVE or HBD.'' This guide assumes you already have: * A working Hive account * Hive Keychain browser extension installed and unlocked * Either '''~$10 of HBD''' OR '''~1000 HIVE''' in your wallet * A basic understanding of what HIVE and HBD are If any of the above is not tru..."

= Swapping HIVE / HBD to SWAP.BTC (and back again) =

''A complete noobs walk-through to converting your Hive tokens into pegged Bitcoin (SWAP.BTC) on Hive-Engine, and then converting them back to HIVE or HBD.''

This guide assumes you already have:

* A working Hive account
* Hive Keychain browser extension installed and unlocked
* Either '''~$10 of HBD''' OR '''~1000 HIVE''' in your wallet
* A basic understanding of what HIVE and HBD are

If any of the above is not true, stop here and read [[Hive Blockchain Basics]] and [[Setting up Hive Keychain]] first.

== TL;DR ==

You cannot swap HBD directly to SWAP.BTC in one click. You have to do it in stages:

# Convert '''HBD → HIVE''' (using @swap.app)
# Move '''HIVE → SWAP.HIVE''' (deposit onto the Hive-Engine sidechain)
# Trade '''SWAP.HIVE → SWAP.BTC''' (on the Hive-Engine market)

To go back, you reverse the whole thing.

Each step costs a small fee. Read the whole guide before you start so you understand what is happening at each stage.

== What is SWAP.BTC anyway? ==

SWAP.BTC is '''not real Bitcoin'''. It is a "pegged" token that lives on Hive-Engine (a smart-contract sidechain of Hive). For every 1 SWAP.BTC that exists, there is supposed to be 1 real BTC held by the gateway operator (@honey-swap) on the actual Bitcoin blockchain. You can withdraw SWAP.BTC out to a real Bitcoin wallet at any time (subject to a minimum withdrawal amount — see below), and it becomes real BTC again.

The same idea applies to '''SWAP.ETH''', '''SWAP.DOGE''', '''SWAP.LTC''', '''SWAP.BNB''', '''SWAP.USDT''' and others.

'''<span style="color:red">Important:</span>''' Pegged tokens rely on a single gateway operator. If that operator vanishes, your SWAP.BTC may not be redeemable for real BTC. Do '''not''' park large sums in pegged tokens long-term. Treat them as a tool for moving value, not a place to store it.

== Step 0: Vocabulary you will need ==

{| class="wikitable"
|-
! Term !! What it means
|-
| HIVE || The native liquid token of the Hive blockchain.
|-
| HBD || Hive Backed Dollar. A stablecoin loosely pegged to $1 USD.
|-
| Hive Power (HP) || Staked HIVE. Not relevant to this guide. Ignore it.
|-
| SWAP.HIVE || A 1:1 wrapped version of HIVE that lives on Hive-Engine. You '''must''' have SWAP.HIVE before you can buy SWAP.BTC.
|-
| Hive-Engine || A sidechain that hosts custom tokens, including all the SWAP.* pegged tokens. Accessed at hive-engine.com.
|-
| @honey-swap || The gateway account that holds the real BTC, ETH, DOGE etc. backing the SWAP tokens.
|-
| Active key || The Hive Keychain key needed to authorise transfers and trades. Keychain handles this for you, but it will pop up asking you to confirm.
|}

== Part 1: Going from HBD or HIVE to SWAP.BTC ==

=== Step 1: (HBD holders only) Convert HBD to HIVE ===

If you already have HIVE and not HBD, '''skip to Step 2'''.

Hive-Engine deposits use HIVE, not HBD. So your $10 of HBD needs to become HIVE first. The easiest way is to use @swap.app:

# Go to your wallet at wallet.hive.blog (or the wallet tab in PeakD / Ecency).
# Click the dropdown next to your '''HBD''' balance and choose '''Transfer'''.
# In the recipient field, type: <code>swap.app</code>
# In the amount field, type the amount of HBD you want to swap (e.g. <code>10.000 HBD</code>).
# Leave the memo '''blank'''. (Sending HBD with no memo means "convert to HIVE".)
# Click '''Send''' and approve in Keychain.
# Within about 30 seconds, an equivalent amount of HIVE (minus a 0.1% fee) will appear in your wallet.

'''Do not''' use the blockchain's built-in HBD → HIVE "convert" button. It takes 3.5 days and uses an averaged price that may give you less HIVE than you expect.

=== Step 2: Move HIVE onto Hive-Engine (HIVE → SWAP.HIVE) ===

Tested and working at the time of writing. This is the algorithm we are sticking with — keep it simple, one site, one route:

# Go to '''hive-engine.com'''.
# Click '''Login''' (top right) and sign in with Hive Keychain. Approve in Keychain.
# Click '''Wallet''' (top menu).
# Find '''SWAP.HIVE''' in the token list. Click '''Deposit'''.
# Select '''HIVE''' as the currency to deposit.
# Enter the amount of HIVE you want to deposit (e.g. <code>10</code>).
# '''There is a 0.75% fee on deposits.''' For 10 HIVE you will receive '''9.925 SWAP.HIVE'''.
# Click '''Deposit'''. Keychain will pop up asking you to confirm a transfer of HIVE to <code>@honey-swap</code> with a memo. '''Do not edit the memo''' — it tells the gateway who to credit. Click '''Confirm'''.
# Wait 30 seconds and refresh. SWAP.HIVE will appear in your Hive-Engine wallet.

'''<span style="color:red">Common mistake:</span>''' If you edit the memo, the gateway will not know which Hive-Engine account to credit, and your funds may be lost. Just leave the memo alone.

=== Step 3: Trade SWAP.HIVE for SWAP.BTC ===

Now you finally get to buy your pegged Bitcoin.

# While still logged into hive-engine.com, click '''Market''' (top menu).
# Search for and select '''SWAP.BTC'''. The trading pair shown will be '''SWAP.BTC / SWAP.HIVE'''.
# You will see two columns of orders:
#* '''Sell orders''' — people offering to sell SWAP.BTC, sorted by lowest price first.
#* '''Buy orders''' — people bidding to buy SWAP.BTC.
# To buy SWAP.BTC instantly, click on the '''lowest sell order''' price. This auto-fills the price field in the '''Buy SWAP.BTC''' box.
# Enter how much SWAP.HIVE you want to spend in the '''Total''' field. The '''Quantity''' (amount of SWAP.BTC you will receive) auto-calculates.
# Double-check the numbers. Click '''Buy'''. Keychain pops up. Approve.
# Refresh your wallet. You should now see SWAP.BTC.

'''<span style="color:red">Sanity check:</span>''' Compare the SWAP.BTC price on Hive-Engine with the real BTC/USD price on a major exchange. They should be close. If SWAP.BTC is trading at a noticeable premium or discount, that reflects market trust in the gateway — be cautious if the gap is large.

== Part 2: Going back (SWAP.BTC → HIVE / HBD) ==

You reverse the chain. Same site, same wallet.

=== Step 4: Trade SWAP.BTC back to SWAP.HIVE ===

# hive-engine.com → '''Market''' → SWAP.BTC.
# This time use the '''Sell SWAP.BTC''' box.
# Click on the highest '''buy order''' to auto-fill the price.
# Enter the SWAP.BTC quantity you want to sell. Click '''Sell'''. Approve in Keychain.
# Your SWAP.HIVE balance increases.

=== Step 5: Move SWAP.HIVE back to HIVE ===

# hive-engine.com → '''Wallet'''.
# Find SWAP.HIVE and click '''Withdraw'''.
# Select '''HIVE''' as the destination.
# Enter the amount. The destination is automatically your own Hive account.
# '''There is a 0.75% fee on withdrawals.''' For 10 SWAP.HIVE you will receive 9.925 HIVE.
# Approve in Keychain.
# Within ~30 seconds, the HIVE appears in your normal Hive wallet.

=== Step 6: (Optional) Convert HIVE back to HBD ===

If you want to end up holding HBD again rather than HIVE:

# Wallet → '''Transfer''' HIVE → recipient: <code>swap.app</code> → memo: <code>hbd</code> → Send.
# A few seconds later, equivalent HBD lands in your wallet.

The memo <code>hbd</code> is what tells @swap.app to convert in this direction. If you forget the memo, it will assume you want HIVE and bounce your tokens back unchanged (or convert HBD to HIVE if that's what you sent).

== Important: getting actual BTC out ==

If your goal is to eventually get '''real Bitcoin''' on the Bitcoin blockchain (rather than just holding SWAP.BTC inside Hive-Engine), be aware:

* '''Minimum withdrawal: 0.01 SWAP.BTC.''' At current BTC prices that is roughly several hundred US dollars. You cannot withdraw less than this directly. Small amounts of SWAP.BTC are essentially trapped on Hive-Engine until you accumulate enough or trade them back.
* The withdrawal also pays the Bitcoin network mining fee plus a gateway fee, which can be significant for small amounts.

'''Workaround for small amounts:''' If you have less than 0.01 SWAP.BTC and want it as real BTC, the practical route is:

# Sell SWAP.BTC → SWAP.HIVE on the Hive-Engine market (Step 4 above).
# Withdraw SWAP.HIVE → HIVE (Step 5 above).
# Send HIVE to a centralised exchange that lists HIVE (e.g. Binance, MEXC, etc. — check current listings).
# Trade HIVE for BTC on that exchange.
# Withdraw BTC from the exchange to your own Bitcoin wallet.

This adds extra trading fees and exchange withdrawal fees, but it is the only viable path when your SWAP.BTC balance is below the 0.01 minimum.

For our $10 / 1000-HIVE example amounts, '''you will not have anywhere near 0.01 SWAP.BTC.''' Treat the SWAP.BTC purchase as an exercise / way to gain BTC price exposure inside Hive-Engine, not as a way to actually move BTC onto the Bitcoin network.

== Fee summary for the full round trip ==

For the simple hive-engine.com path described above:

{| class="wikitable"
|-
! Stage !! Approximate fee
|-
| HBD → HIVE (swap.app) || 0.1%
|-
| HIVE → SWAP.HIVE (hive-engine.com deposit) || 0.75%
|-
| SWAP.HIVE → SWAP.BTC (market trade) || 1%
|-
| SWAP.BTC → SWAP.HIVE (market trade) || 1%
|-
| SWAP.HIVE → HIVE (hive-engine.com withdrawal) || 0.75%
|-
| HIVE → HBD (swap.app) || 0.1%
|-
| '''Total round trip''' || '''~3.7%''' (plus market spread)
|}

Plus you are exposed to BTC price movement the whole time SWAP.BTC sits in your wallet. Don't expect to round-trip $10 and come out ahead — the fees alone will eat about 37 cents.

== Things that go wrong ==

; "I deposited HIVE and nothing showed up in Hive-Engine."
: Wait 2–3 minutes and refresh. If still nothing, check that the memo on the original transfer was the one Hive-Engine generated. Look up your transaction on hiveblocks.com to verify it sent successfully. Contact @honey-swap on Hive Discord if it has been more than an hour.

; "My SWAP.BTC trade is sitting as an open order, not filling."
: You set your buy price too low (or sell price too high). Either wait, or cancel the order and re-place it at a price that matches an existing counter-order.

; "The withdraw button is rejecting my SWAP.BTC withdrawal."
: You are likely below the 0.01 SWAP.BTC minimum. See the "Important: getting actual BTC out" section above for the workaround.

; "Keychain didn't pop up."
: Make sure the extension is installed, unlocked, and that you allowed the site permission. Refresh the page and try again.

== Security reminders ==

* '''Never''' paste your master password or any private key into Hive-Engine, swap.app or any other website. Keychain handles signing for you. If a site asks you to type a key directly, it is either old/janky or a phishing site.
* Pegged SWAP tokens are only as trustworthy as their gateway operator. @honey-swap has been reliable for years, but reliable is not the same as risk-free.
* Always test with a small amount first. Move $1 before you move $1000.
* Bookmark the official URL (hive-engine.com). Do not click "Hive-Engine" links from random comments — phishing clones exist.

== References ==

* neopch (2025) — VIDEO TUTORIAL: How to Exchange Hive to SWAP.HIVE using Hive-Engine and PeakD. Confirms 0.75% deposit/withdrawal fee. ''hive.blog/hive-167922/@neopch/tdkoabkc''

== See also ==

* [[Hive Blockchain Basics]]
* [[Setting up Hive Keychain]]
* [[How to keep your Hive keys safe]]
* [[Glossary of Hive terms]]

[[Category:Hive]]
[[Category:Cryptocurrency]]
[[Category:Tutorials]]

Resetting Forgotten GNOME Keyring in Ubuntu MATE

2026-04-30T23:18:15Z

AwesomO: Created page with "== Resetting Forgotten GNOME Keyring == If you forget your keyring password or see the error ''"OS keyring is not available for encryption,"'' you must reset the local keyring storage. === Method 1: Terminal (Recommended) === This deletes existing keyring files so the system can generate a fresh one. # Open the terminal. # Run the following command: #: <syntaxhighlight lang="bash">rm ~/.local/share/keyrings/*.keyring</syntaxhighlight> # '''Log out''' and log back in. #..."

== Resetting Forgotten GNOME Keyring ==

If you forget your keyring password or see the error ''"OS keyring is not available for encryption,"'' you must reset the local keyring storage.

=== Method 1: Terminal (Recommended) ===
This deletes existing keyring files so the system can generate a fresh one.
# Open the terminal.
# Run the following command:
#: <syntaxhighlight lang="bash">rm ~/.local/share/keyrings/*.keyring</syntaxhighlight>
# '''Log out''' and log back in.
# When prompted by an app (like Chrome or VS Code), enter a new password.
#* '''Note:''' Use your system login password if you want it to unlock automatically.

=== Method 2: Graphical Interface ===
# Open '''Passwords and Keys''' (Seahorse) from the application menu.
# Right-click the '''Login''' or '''Default''' keyring in the left sidebar.
# Select '''Delete'''.
# Restart the session.

=== Fixing "Keyring Not Available" Errors ===
If the keyring is installed but not starting, ensure the following packages are present:
* <code>gnome-keyring</code>
* <code>libsecret-1-0</code>

To install them:
<syntaxhighlight lang="bash">
sudo apt update && sudo apt install gnome-keyring libsecret-1-0
</syntaxhighlight>

[[Category:Troubleshooting]]
[[Category:Ubuntu MATE]]

Delegate Hive Power (HP) to Another Account

2026-04-27T11:02:17Z

AwesomO: Created page with "= Delegate Hive Power (HP) to Another Account = '''CompleteNoobs Walkthrough''' ''How to lend your Hive Power (HP) to another account safely and easily'' == What is HP Delegation? == Hive Power (HP) is your staked HIVE. When you '''delegate''' HP to another account, you are temporarily lending them your voting power and Resource Credits (RC). - You still '''own''' the HP 100%. - The other person can use the voting power to upvote posts. - You can take it back when..."

= Delegate Hive Power (HP) to Another Account =

'''CompleteNoobs Walkthrough'''
''How to lend your Hive Power (HP) to another account safely and easily''

== What is HP Delegation? ==
Hive Power (HP) is your staked HIVE. When you '''delegate''' HP to another account, you are temporarily lending them your voting power and Resource Credits (RC).

- You still '''own''' the HP 100%.
- The other person can use the voting power to upvote posts.
- You can take it back whenever you want (undelegate).
- This is very common on Hive to support projects, friends, curators, or to rent voting power.

== Why Would You Do This? ==
- Help a friend or project get more voting power
- Support a curation team or witness
- Earn a small fee by renting your HP (some people do this)
- Move voting power between your own accounts

== Important Warnings (Read This First) ==
'''⚠️ Only delegate what you are comfortable lending.'''
'''⚠️ Never share your private keys or posting key.'''
'''⚠️ Always double-check the "To" account name before confirming.'''
'''⚠️ Start with a small test amount (e.g. 10 HP) the first time.'''
'''⚠️ Use trusted interfaces only (PeakD or Hive Keychain recommended).'''

== Prerequisites ==
- A Hive account with some Hive Power (HP)
- Either:
- Hive Keychain browser extension (recommended), '''or'''
- Access to PeakD.com

== Method 1: Easiest – Using PeakD.com (Web Interface) ==

=== Step 1: Go to PeakD ===
# Open your browser and go to: [https://peakd.com/ https://peakd.com/]
# Click '''Login''' (top right) and log in with '''Hive Keychain''' (easiest) or your posting/active key.

=== Step 2: Open Your Wallet ===
# Click on your username (top right) → '''Wallet'''

=== Step 3: Start the Delegation ===
# In the wallet, look for the big blue button that says '''Delegate HP''' (or "Power Delegation").
# If you don't see it immediately, scroll down to the '''"Delegations"''' section and click '''Delegate'''.

=== Step 4: Fill in the Details ===
# In the popup/window that appears:
#* '''To:''' → Type the exact Hive username you want to delegate to (e.g. <code>@completenoobs</code>)
#* '''Amount:''' → Enter how much HP you want to delegate (you can use decimals, e.g. <code>50.123</code>)
#* (Optional) Add a memo if you want

=== Step 5: Confirm and Send ===
# Review everything carefully.
# Click '''Delegate''' or '''Confirm'''.
# Approve the transaction in Hive Keychain (or enter your active key if using manual login).
# You should see a green success message.

'''Done!''' The HP is now delegated.

== Method 2: Fastest – Using Hive Keychain Extension (Recommended) ==

This is the quickest way once you have the extension installed.

=== Step 1: Install Hive Keychain (if you haven't) ===
# Go to the Chrome Web Store (or Firefox Add-ons) and search for '''"Hive Keychain"'''.
# Install it and set it up with your Hive account.

=== Step 2: Open Keychain ===
# Click the little Hive Keychain icon in your browser toolbar.
# Make sure you are logged into the account that has the HP.

=== Step 3: Choose Delegate ===
# In the Keychain popup, click the '''Delegate''' button (it usually has a little arrow icon).

=== Step 4: Enter Details ===
# Fill in:
#* '''Delegate to:''' → The username (without the @)
#* '''Amount:''' → How much HP to send
# Click '''Next''' → Review → '''Confirm'''

'''Done!''' Super fast.

== How to Check Your Current Delegations ==

=== On PeakD ===
# Go to your Wallet → scroll down to the '''Delegations''' tab.
# You will see two sections:
#* '''Outgoing''' (what you have delegated to others)
#* '''Incoming''' (what others have delegated to you)

=== On Hive Keychain ===
# Click the Keychain icon → '''Delegations''' tab.

== How to Undelegate (Take Your HP Back) ==

The process is almost identical to delegating:

1. Go back to PeakD Wallet or Hive Keychain.
2. Find the delegation you want to cancel.
3. Click '''Undelegate''' (or set the amount to 0).
4. Confirm the transaction.

'''Note:''' On Hive, undelegation usually returns the power within a few minutes to a few hours (much faster than the old Steem 5-day cooldown).

== Advanced: Using the Command Line (CLI) ==

Only do this if you are comfortable with the terminal.

Using <code>beem</code> Python library (example):

<pre>
beempy delegate @youraccount @targetaccount 100 HP
</pre>

Or using the official hived CLI (more advanced).
== Common Questions ==
* '''Q: Can I delegate all my HP?'''
A: Yes, but leave a little for yourself so you can still make transactions (you need some RC).
* '''Q: Do I still earn rewards on delegated HP?'''
A: Yes — you still own the HP and continue to receive the 10% annual inflation reward on it. Only the '''voting power''' is lent.
* '''Q: Is there a fee?'''
A: No delegation fee on Hive (only tiny blockchain resource cost).
*'''Q: Can the person I delegate to steal my HP?'''
A: No. They can only use the voting power. You always keep ownership.

Main Page

2026-04-27T01:31:37Z

AwesomO: /* In Concept development Mode - a wiki you can download */

=In Concept development Mode - a wiki you can download=

* [https://www.completenoobs.com/noobs/V4call-v0.11| cnoobs.com on hold while working on v4call]
* https://github.com/CompleteNoobs/v4call

= CompleteNoobs: A Downloadable Wiki for Reproducible Computer Tutorials =

'''CompleteNoobs''' is a open-source wiki offering free, reproducible computer science tutorials.

* [[Ubuntu2404_Install_Docker_and_Docker_Compose| Download the wiki as a '''Docker image''' to run locally on your computer or fork it to contribute and share knowledge.]]

== About CompleteNoobs ==

Our mission is to provide accessible, libre-licensed resources for hobbyists, sysadmins, students, teachers, and computer science enthusiasts. All content is available under a '''Creative Commons BY-NC-SA''' license, ensuring the freedoms to:
* Read
* Edit/Modify
* Copy
* Share freely

Download the wiki as an XML file at [https://xml.completenoobs.com xml.completenoobs.com] or access data-heavy content (images, videos, audio) via '''IPFS''' hashes.

== Get Started ==

* '''Download the Wiki''': Run CompleteNoobs locally using our [[Local_CompleteNoobs_Wiki|Manually install guides or Docker image]].
* '''Host Your Own''': Set up your own MediaWiki instance with our guide: [[Host_Your_Own_Mediawiki_Online|Host Your Own MediaWiki Online]].

== CompleteNoobs Blockchain Project ==

As Noobs we want to learn more about bitcoin, without losing any real bitcoin

First we are learning how to fork bitcoin version 0.14.3, best way to learn is by tinkering with it.
* [[N33Bcoin| n33b.com]]

== Essential Links ==

* [[Main_Index|Main Index Page]]
* [[Special:AllPages|All Pages]]
* [[Wiki_Basic_Syntax|Wiki Basic Syntax]]
* [[COMPLETENOOBS_FUNDING|Support Us]]

== Licenses ==
[[LICENCE_HEADERS]]
All content is libre-licensed for free copying, modification, and distribution. Add a license header to your contributions using:
<pre>{{:LICENCE_HEADER_CC0}}</pre>
{{:LICENCE_HEADER_CC0}}

== Disclaimer ==

<div class="toccolours mw-collapsible mw-collapsed">
'''''DISCLAIMER:'''''
<div class="mw-collapsible-content">
Content on CompleteNoobs is for informational and educational purposes only. We make no warranties about accuracy or reliability. Use at your own risk. Links to external sites are not endorsements, and we are not responsible for their content or availability. The site may be temporarily unavailable due to technical issues beyond our control.
</div>
</div>

{{Special:ContributionScores/10/5}}
{{Special:PopularPages/10}}

Main Page

2026-04-27T01:11:48Z

AwesomO: /* In Concept development Mode - a wiki you can download */

=In Concept development Mode - a wiki you can download=

* [https://www.completenoobs.com/noobs/V4call-v0.11| cnoobs.com on hold while working on v4call]

= CompleteNoobs: A Downloadable Wiki for Reproducible Computer Tutorials =

'''CompleteNoobs''' is a open-source wiki offering free, reproducible computer science tutorials.

* [[Ubuntu2404_Install_Docker_and_Docker_Compose| Download the wiki as a '''Docker image''' to run locally on your computer or fork it to contribute and share knowledge.]]

== About CompleteNoobs ==

Our mission is to provide accessible, libre-licensed resources for hobbyists, sysadmins, students, teachers, and computer science enthusiasts. All content is available under a '''Creative Commons BY-NC-SA''' license, ensuring the freedoms to:
* Read
* Edit/Modify
* Copy
* Share freely

Download the wiki as an XML file at [https://xml.completenoobs.com xml.completenoobs.com] or access data-heavy content (images, videos, audio) via '''IPFS''' hashes.

== Get Started ==

* '''Download the Wiki''': Run CompleteNoobs locally using our [[Local_CompleteNoobs_Wiki|Manually install guides or Docker image]].
* '''Host Your Own''': Set up your own MediaWiki instance with our guide: [[Host_Your_Own_Mediawiki_Online|Host Your Own MediaWiki Online]].

== CompleteNoobs Blockchain Project ==

As Noobs we want to learn more about bitcoin, without losing any real bitcoin

First we are learning how to fork bitcoin version 0.14.3, best way to learn is by tinkering with it.
* [[N33Bcoin| n33b.com]]

== Essential Links ==

* [[Main_Index|Main Index Page]]
* [[Special:AllPages|All Pages]]
* [[Wiki_Basic_Syntax|Wiki Basic Syntax]]
* [[COMPLETENOOBS_FUNDING|Support Us]]

== Licenses ==
[[LICENCE_HEADERS]]
All content is libre-licensed for free copying, modification, and distribution. Add a license header to your contributions using:
<pre>{{:LICENCE_HEADER_CC0}}</pre>
{{:LICENCE_HEADER_CC0}}

== Disclaimer ==

<div class="toccolours mw-collapsible mw-collapsed">
'''''DISCLAIMER:'''''
<div class="mw-collapsible-content">
Content on CompleteNoobs is for informational and educational purposes only. We make no warranties about accuracy or reliability. Use at your own risk. Links to external sites are not endorsements, and we are not responsible for their content or availability. The site may be temporarily unavailable due to technical issues beyond our control.
</div>
</div>

{{Special:ContributionScores/10/5}}
{{Special:PopularPages/10}}

HTML Expanding info box

2026-04-27T01:08:48Z

AwesomO: /* Full Example Page */

== How to Add an Expanding Info Box (Simple Guide)==

{| class="wikitable"
|-
! Feature
! Value
|-
| Method
| <details> + <summary>
|-
| JavaScript
| Not needed
|-
| Mobile Support
| Yes
|-
| Difficulty
| Very Easy
|}

=== Basic Example===

<pre>
<details>
<summary>What you will like</summary>

<div>
<p>This content is hidden until clicked.</p>
<code>print "hello content"</code>
</div>

</details>
</pre>

=== Optional CSS Styling===

<pre>
body {
font-family: sans-serif;
}

details {
border: 1px solid #aaa;
margin: 20px 0;
padding: 5px;
}

summary {
font-weight: bold;
cursor: pointer;
}
</pre>

=== Dark Mode (Optional)===

<pre>
@media (prefers-color-scheme: dark) {
details {
background: #222;
color: #ddd;
border: 1px solid #555;
}

summary {
color: #fff;
}
}
</pre>

=== Full Example Page===

<pre>
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>Example</title>

<style>
body {
font-family: sans-serif;
max-width: 800px;
margin: 40px auto;
padding: 20px;
}

details {
border: 1px solid #aaa;
margin: 20px 0;
padding: 5px;
background: #f9f9f9;
}

summary {
font-weight: bold;
cursor: pointer;
}

/* Dark Mode */
@media (prefers-color-scheme: dark) {
body {
background: #111;
color: #ddd;
}

details {
background: #222;
border: 1px solid #555;
}

summary {
color: #fff;
}
}
</style>
</head>

<body>

<h1>Example Page</h1>

<details>
<summary>What you will like</summary>
<div>
<p>Hidden content here...</p>
<code>print "hello content"</code>
</div>
</details>

</body>
</html>
</pre>


<div class="toccolours mw-collapsible mw-collapsed">
Another example:
<div class="mw-collapsible-content">

<pre>
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>completenoobs.com</title>
<style>
body { font-family: system-ui, -apple-system, sans-serif; max-width: 800px; margin: 40px auto; padding: 20px; line-height: 1.6; }

details {
border: 1px solid #ddd;
border-radius: 8px;
margin: 25px 0;
background: #f9f9f9;
}
summary {
padding: 15px 20px;
font-weight: bold;
cursor: pointer;
background: #f0f0f0;
border-radius: 8px 8px 0 0;
}
.mw-collapsible-content { padding: 20px; }

/* Dark Mode */
@media (prefers-color-scheme: dark) {
details { border: 1px solid #555; background: #1e1e1e; color: #ddd; }
summary { background: #2a2a2a; color: #eee; }
.mw-collapsible-content { color: #ccc; }
}
</style>
</head>
<body>

<h1>Welcome to completenoobs.com</h1>

<details>
<summary>What you will like</summary>
<div class="mw-collapsible-content">
<p>Put all your hidden content here...</p>
<code>print "hello content"</code>
</div>
</details>

</body>
</html>

</pre>

</div>
</div>

=== Tips===

* To open by default: <code><details open></code>
* Duplicate the block to create more sections
* Works without CSS (just looks basic)

<div class="toccolours mw-collapsible mw-collapsed">
The CSS explained:
<div class="mw-collapsible-content">

'''What is CSS?'''

CSS is what makes things look nice.

* HTML = the structure (the box)
* CSS = the style (colors, spacing, fonts)

----

'''The Page (body)'''
<pre>
body {
font-family: sans-serif;
max-width: 800px;
margin: 40px auto;
padding: 20px;
}
</pre>

This controls the whole page:

* Changes the font
* Keeps the page centered
* Adds space so things are easy to read

----

'''The Box (details)'''
<pre>
details {
border: 1px solid #aaa;
margin: 20px 0;
padding: 5px;
background: #f9f9f9;
}
</pre>

This is the expandable box:

* Border = thin line around it
* Margin = space outside the box
* Padding = space inside the box
* Background = box color

----

'''The Clickable Title (summary)'''
<pre>
summary {
font-weight: bold;
cursor: pointer;
}
</pre>

This is what you click:

* Bold text
* Mouse turns into a hand

----

'''Dark Mode (automatic)'''
<pre>
@media (prefers-color-scheme: dark) {
</pre>

This means:

"If the user is using dark mode, use different colors"

----

'''Dark Mode Colours'''
<pre>
body {
background: #111;
color: #ddd;
}

details {
background: #222;
border: 1px solid #555;
}

summary {
color: #fff;
}
</pre>

This makes:

* Dark background
* Light text
* Darker boxes

----

'''How to Change Colours'''

* Darker background → change <code>#111</code>
* Lighter text → change <code>#ddd</code>
* Box color → change <code>#222</code>

Examples:

* <code>#000</code> = pure black
* <code>#fff</code> = pure white
* <code>#1a1a1a</code> = softer black

----

'''Force Dark Mode (always on)'''

Remove the <code>@media</code> line and just use:

<pre>
body {
background: #111;
color: #ddd;
}
</pre>

----

'''Super Simple Summary'''

* CSS = makes things look nice
* details = the box
* summary = the clickable title
* dark mode = automatic color switch

</div>
</div>

HTML Expanding info box

2026-04-27T01:02:11Z

AwesomO: Created page with "== How to Add an Expanding Info Box (Simple Guide)== {| class="wikitable" |- ! Feature ! Value |- | Method | <details> + <summary> |- | JavaScript | Not needed |- | Mobile Support | Yes |- | Difficulty | Very Easy |} === Basic Example=== <pre> <details> <summary>What you will like</summary> <div> <p>This content is hidden until clicked.</p> <code>print "hello content"</code> </div> </details> </pre> === Optional CSS Styling=== <pre> body {..."

== How to Add an Expanding Info Box (Simple Guide)==

{| class="wikitable"
|-
! Feature
! Value
|-
| Method
| <details> + <summary>
|-
| JavaScript
| Not needed
|-
| Mobile Support
| Yes
|-
| Difficulty
| Very Easy
|}

=== Basic Example===

<pre>
<details>
<summary>What you will like</summary>

<div>
<p>This content is hidden until clicked.</p>
<code>print "hello content"</code>
</div>

</details>
</pre>

=== Optional CSS Styling===

<pre>
body {
font-family: sans-serif;
}

details {
border: 1px solid #aaa;
margin: 20px 0;
padding: 5px;
}

summary {
font-weight: bold;
cursor: pointer;
}
</pre>

=== Dark Mode (Optional)===

<pre>
@media (prefers-color-scheme: dark) {
details {
background: #222;
color: #ddd;
border: 1px solid #555;
}

summary {
color: #fff;
}
}
</pre>

=== Full Example Page===

<pre>
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>Example</title>

<style>
body {
font-family: sans-serif;
max-width: 800px;
margin: 40px auto;
padding: 20px;
}

details {
border: 1px solid #aaa;
margin: 20px 0;
padding: 5px;
background: #f9f9f9;
}

summary {
font-weight: bold;
cursor: pointer;
}

/* Dark Mode */
@media (prefers-color-scheme: dark) {
body {
background: #111;
color: #ddd;
}

details {
background: #222;
border: 1px solid #555;
}

summary {
color: #fff;
}
}
</style>
</head>

<body>

<h1>Example Page</h1>

<details>
<summary>What you will like</summary>
<div>
<p>Hidden content here...</p>
<code>print "hello content"</code>
</div>
</details>

</body>
</html>
</pre>
</pre>

=== Tips===

* To open by default: <code><details open></code>
* Duplicate the block to create more sections
* Works without CSS (just looks basic)

<div class="toccolours mw-collapsible mw-collapsed">
The CSS explained:
<div class="mw-collapsible-content">

'''What is CSS?'''

CSS is what makes things look nice.

* HTML = the structure (the box)
* CSS = the style (colors, spacing, fonts)

----

'''The Page (body)'''
<pre>
body {
font-family: sans-serif;
max-width: 800px;
margin: 40px auto;
padding: 20px;
}
</pre>

This controls the whole page:

* Changes the font
* Keeps the page centered
* Adds space so things are easy to read

----

'''The Box (details)'''
<pre>
details {
border: 1px solid #aaa;
margin: 20px 0;
padding: 5px;
background: #f9f9f9;
}
</pre>

This is the expandable box:

* Border = thin line around it
* Margin = space outside the box
* Padding = space inside the box
* Background = box color

----

'''The Clickable Title (summary)'''
<pre>
summary {
font-weight: bold;
cursor: pointer;
}
</pre>

This is what you click:

* Bold text
* Mouse turns into a hand

----

'''Dark Mode (automatic)'''
<pre>
@media (prefers-color-scheme: dark) {
</pre>

This means:

"If the user is using dark mode, use different colors"

----

'''Dark Mode Colours'''
<pre>
body {
background: #111;
color: #ddd;
}

details {
background: #222;
border: 1px solid #555;
}

summary {
color: #fff;
}
</pre>

This makes:

* Dark background
* Light text
* Darker boxes

----

'''How to Change Colours'''

* Darker background → change <code>#111</code>
* Lighter text → change <code>#ddd</code>
* Box color → change <code>#222</code>

Examples:

* <code>#000</code> = pure black
* <code>#fff</code> = pure white
* <code>#1a1a1a</code> = softer black

----

'''Force Dark Mode (always on)'''

Remove the <code>@media</code> line and just use:

<pre>
body {
background: #111;
color: #ddd;
}
</pre>

----

'''Super Simple Summary'''

* CSS = makes things look nice
* details = the box
* summary = the clickable title
* dark mode = automatic color switch

</div>
</div>

V4call-v0.11

2026-04-25T01:49:08Z

AwesomO: Created page with "{{:LICENCE_HEADER_MIT}} = v4call — Deploy Your Own Server on Ubuntu 24.04 with Docker = From CompleteNoobs This guide walks through deploying your own v4call server from scratch on a fresh Vultr Ubuntu 24.04 VPS — from first login to a working HTTPS video/audio calling service on your own domain, optionally federated with other v4call servers. v4call is an open-source, decentralised video and audio calling platform that uses Hive blockchain for identity and HBD..."

{{:LICENCE_HEADER_MIT}}

= v4call — Deploy Your Own Server on Ubuntu 24.04 with Docker =

From CompleteNoobs

This guide walks through deploying your own v4call server from scratch on a fresh Vultr Ubuntu 24.04 VPS — from first login to a working HTTPS video/audio calling service on your own domain, optionally federated with other v4call servers.

v4call is an open-source, decentralised video and audio calling platform that uses Hive blockchain for identity and HBD micropayments. It supports custom Hive-Engine token payments, encrypted direct messages with persistent chat history, voice-only and video calls, and a free-market platform fee system. Fork it, run your own server, keep all your platform fees, join the federation.

'''Source code''': [https://github.com/CompleteNoobs/v4call https://github.com/CompleteNoobs/v4call]

'''End result''': A working v4call server at <code>https://call.yourdomain.com</code> that you can log into with a Hive account, optionally connected to other v4call servers via federation.

== Contents ==

* [[#What_You_Need|1 What You Need]]
* [[#Step_1:_Create_Your_Vultr_VPS|2 Step 1: Create Your Vultr VPS]]
* [[#Step_2:_Point_Your_Domain_at_the_VPS|3 Step 2: Point Your Domain at the VPS]]
* [[#Step_3:_Log_into_Your_VPS|4 Step 3: Log into Your VPS]]
* [[#Step_4:_Update_the_Server|5 Step 4: Update the Server]]
* [[#Step_5:_Install_Docker|6 Step 5: Install Docker]]
* [[#Step_6:_Install_Git|7 Step 6: Install Git]]
* [[#Step_7:_Fork_and_Clone_the_Code|8 Step 7: Fork and Clone the Code]]
* [[#Step_8:_Configure_Your_Server_(.env_file)|9 Step 8: Configure Your Server (.env file)]]
* [[#Step_9:_Configure_Nginx_—_HTTP_Only_First|10 Step 9: Configure Nginx — HTTP Only First]]
* [[#Step_10:_Create_Data_Directories_and_Fix_Permissions|11 Step 10: Create Data Directories and Fix Permissions]]
* [[#Step_11:_Build_and_Start_the_Server|12 Step 11: Build and Start the Server]]
* [[#Step_12:_Get_Your_SSL_Certificate|13 Step 12: Get Your SSL Certificate]]
* [[#Step_13:_Enable_HTTPS_in_Nginx|14 Step 13: Enable HTTPS in Nginx]]
* [[#Step_14:_Set_Up_SSL_Auto-Renewal|15 Step 14: Set Up SSL Auto-Renewal]]
* [[#Step_15:_Test_Everything_is_Working|16 Step 15: Test Everything is Working]]
* [[#Step_16:_Set_Up_Your_Call_Rates_on_Hive|17 Step 16: Set Up Your Call Rates on Hive]]
* [[#Step_17:_Federation_Setup_(Optional)|18 Step 17: Federation Setup (Optional)]]
* [[#Feature_Guide:_What_Your_Server_Can_Do|19 Feature Guide: What Your Server Can Do]]
* [[#Admin_Configuration_Reference|20 Admin Configuration Reference]]
* [[#Updating_Your_Server|21 Updating Your Server]]
* [[#Common_Problems_and_Fixes|22 Common Problems and Fixes]]
* [[#Quick_Reference|23 Quick Reference]]

== What You Need ==

Before starting, make sure you have the following:

* '''A Vultr account''' — sign up at [https://vultr.com vultr.com] - please use are [https://www.vultr.com/?ref=7704739 Vultr Referral link] to help us cover server costs.
* '''A domain name''' with DNS access — e.g. <code>call.yourdomain.com</code>
* '''Two Hive accounts''' — one for your server identity (receives platform fees), one for escrow (holds caller funds during calls). Create free accounts at [https://signup.hive.io signup.hive.io]
* '''Hive Keychain browser extension''' — for login and payments. Install from [https://hive-keychain.com hive-keychain.com]
* '''A GitHub account''' — free at [https://github.com github.com]. You will fork the v4call project.
* '''A terminal''' — Mac: Terminal app. Windows: PowerShell or PuTTY.

You do not need to know how to code. Every command can be copy-pasted exactly as shown.

== Step 1: Create Your Vultr VPS ==

# Log into [https://my.vultr.com my.vultr.com]
# Click '''Deploy New Server'''
# Choose '''Cloud Compute — Shared CPU'''
# Choose a location close to you
# Choose '''Ubuntu 24.04 LTS x64'''
# Choose the '''$6/month''' plan (1 CPU, 1GB RAM)
# Set Server Hostname to something like <code>v4call-server</code>
# Click '''Deploy Now'''

Wait ~60 seconds for it to start. Click the server to find:
* '''IP Address''' — looks like <code>123.456.789.012</code> — write it down
* '''Password''' — click the eye icon — write it down

== Step 2: Point Your Domain at the VPS ==

Log into your DNS provider and add an A record:

{| class="wikitable"
|-
! Field !! Value
|-
| Type || A
|-
| Name || <code>call</code> (or <code>@</code> for root domain)
|-
| Value || Your VPS IP address
|-
| TTL || 300
|}

DNS takes a few minutes to propagate. Check from your computer later:

nslookup call.yourdomain.com

Must show your VPS IP before Step 12. You can continue with all other steps while waiting.

== Step 3: Log into Your VPS ==

Open a terminal on your computer:

ssh root@YOUR_SERVER_IP
* NOTE: you can also do <code>root@your-domain.com</code>

Type <code>yes</code> when asked about the fingerprint, then paste the password from Vultr (right-click to paste in most terminals).

When you see <code>root@v4call-server:~#</code> you are in.

== Step 4: Update the Server ==

apt update && apt upgrade -y

Wait for it to complete (1-2 minutes).

== Step 5: Install Docker ==

Install Docker using the official installer script:

curl -fsSL https://get.docker.com | sh

Verify:

docker --version

Should show <code>Docker version 26.x.x</code> or similar.

Install Docker Compose plugin:

apt install -y docker-compose-plugin

Verify:

docker compose version

Should show <code>Docker Compose version v2.x.x</code>.

== Step 6: Install Git ==

apt install -y git
git --version

== Step 7: Fork and Clone the Code ==

=== Clone onto your VPS ===

cd /opt
git clone https://github.com/CompleteNoobs/v4call.git
cd v4call

==== Fork on GitHub - Optional ====

Forking gives you your own copy of the code that you can customise — change the name, branding, fees — without affecting the original project.

# Go to [https://github.com/CompleteNoobs/v4call https://github.com/CompleteNoobs/v4call]
# Click the '''Fork''' button (top right of the page)
# Select your GitHub account as the destination
# Click '''Create fork'''

You now have your own copy at <code>https://github.com/YOURUSERNAME/v4call</code>

==== Clone onto your VPS ====

cd /opt
git clone https://github.com/YOURUSERNAME/v4call.git
cd v4call

List the files to confirm:

ls

You should see: <code>server.js public/ Dockerfile docker-compose.yml nginx/ package.json .env.example README.md</code>

'''Worth knowing about the <code>public/</code> folder''' — alongside the main UI (<code>index.html</code>) you'll find:

* <code>rate-editor.html</code> — generates your rates post for Hive
* <code>server-sign.html</code> — generates the signed federation verify file (used in [[#Step_17:_Federation_Setup_(Optional)|Federation Setup]] below)
* <code>server-announce.html</code> — publishes your server to the on-chain federation directory
* <code>admin-peers.html</code> — manages your federation peer list
* <code>info.html</code> — public landing page for visitors who haven't logged in
* <code>.well-known/v4call-server.json</code> — placeholder; each operator overwrites this with their own signed file in [[#Step_17:_Federation_Setup_(Optional)|Federation Setup]]

== Step 8: Configure Your Server (.env file) ==

All settings live in a single <code>.env</code> file. Copy the template:

cp .env.example .env
nano .env

Fill in your values:

<pre>
# ── Server Identity ──────────────────────────────────────
SERVER_NAME=yourcallapp
SERVER_DOMAIN=call.yourdomain.com
SERVER_HIVE_ACCOUNT=yourhiveaccount
ESCROW_ACCOUNT=yourescrowaccount
V4CALL_ESCROW_KEY=5Kxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# Secret key to access /admin/* endpoints.
# Choose a long random string — treat it like a password.
# Example: openssl rand -hex 32
ADMIN_KEY=make-up-a-long-random-string-at-least-20-characters

# ── Hive Blockchain ──────────────────────────────────────
CHAIN=hive
HIVE_API=

# ── Platform Fee ─────────────────────────────────────────
# Percentage your server takes from each paid call/DM (10 = 10%)
# This is the MINIMUM fee — users whose rates post sets a lower
# platform fee will be rejected. Users who set a higher fee
# get the best price (your server's rate, not their higher number).
DEFAULT_PLATFORM_FEE=10

# ── Network ──────────────────────────────────────────────
PORT=3000
BIND_HOST=127.0.0.1

# ── Chat Storage ─────────────────────────────────────────
# How many days to keep stored DMs before automatic cleanup
DM_RETENTION_DAYS=33
# How many days to keep stored room messages before cleanup
ROOM_RETENTION_DAYS=33
# How many recent DMs per conversation to show on login (0 = off)
DM_PREVIEW_COUNT=1

# ── Call Behaviour (advanced — defaults are fine) ────────
# CALL_COOLDOWN_MS=30000
# MAX_CALL_DURATION_MIN=120
# PAYMENT_VERIFY_RETRIES=3
# PAYMENT_VERIFY_DELAY_MS=5000

# ── Federation (optional) ────────────────────────────────
# Comma-separated list of peer v4call server federation WebSocket URLs.
# Leave blank for standalone mode (no federation).
# Servers listed here are auto-approved on startup. Discovered peers
# (via Hive directory) need manual approval at /admin-peers.html.
# Example two-server setup:
# On call.completenoobs.com → FEDERATION_PEERS=wss://hive-book.com/federation
# On hive-book.com → FEDERATION_PEERS=wss://call.completenoobs.com/federation
FEDERATION_PEERS=
</pre>

Key points:

* <code>V4CALL_ESCROW_KEY</code> — must be the '''active''' private key for your escrow account. Find it in your Hive wallet → Keys & Permissions → Active. Starts with <code>5K</code>. '''Never share this.'''
* <code>ADMIN_KEY</code> — invent a secret password for accessing admin tools
* <code>HIVE_API</code> — leave blank to use all built-in Hive nodes automatically
* <code>DEFAULT_PLATFORM_FEE</code> — your server's minimum platform fee percentage. See [[#Platform_Fee_System|Platform Fee System]] below for how this works.
* <code>DM_RETENTION_DAYS</code> / <code>ROOM_RETENTION_DAYS</code> — how long chat messages are kept in the database. A cleanup job runs every hour and deletes anything older. Set to <code>0</code> to keep messages indefinitely (not recommended).
* <code>DM_PREVIEW_COUNT</code> — when a user logs in, this many recent DMs per conversation are loaded into the lobby chat so they can see previews. Set to <code>0</code> to disable previews (users still get an unread count alert).
* <code>FEDERATION_PEERS</code> — leave blank for now. You can add peers later (see [[#Step_17:_Federation_Setup_(Optional)|Federation Setup]]).

Save: '''Ctrl+X''' → '''Y''' → '''Enter'''

== Step 9: Configure Nginx — HTTP Only First ==

'''This step is critical.''' A very common mistake is putting the HTTPS/SSL config in Nginx before getting the certificate. Nginx tries to load the certificate at startup — if the file doesn't exist yet, Nginx crashes in a restart loop. Certbot then cannot serve the challenge because Nginx is down. Result: no certificate, stuck in a loop.

The fix: always start with HTTP only, get the certificate, then add HTTPS.

Edit the Nginx config:

nano /opt/v4call/nginx/v4call.conf

Delete everything and replace with this HTTP-only config:

<pre>
server {
listen 80;
server_name call.yourdomain.com www.call.yourdomain.com;

# Certbot challenge path — do not remove this block
location /.well-known/acme-challenge/ {
root /var/www/certbot;
}

# Proxy all other requests to the v4call app
location / {
proxy_pass http://app:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_read_timeout 86400;
}
}
</pre>

Replace <code>call.yourdomain.com</code> with your actual domain in both places.

Save: '''Ctrl+X''' → '''Y''' → '''Enter'''

== Step 10: Create Data Directories and Fix Permissions ==

Create the folders Docker uses for persistent data:

mkdir -p /opt/v4call/data/logs \
mkdir -p /opt/v4call/data/certbot/conf \
mkdir -p /opt/v4call/data/certbot/www/.well-known/acme-challenge \
mkdir -p /opt/v4call/data/certbot/logs

'''Fix permissions — do not skip this.'''

The v4call app runs inside Docker as user <code>node</code> (UID 1000). On the host, these directories are created by root, so the container cannot write to them. This causes a <code>SQLITE_CANTOPEN</code> error that crashes the app.

Fix the logs directory for the app:

chown -R 1000:1000 /opt/v4call/data/logs

Certbot runs as root so its directories stay root-owned:

chown -R root:root /opt/v4call/data/certbot
chmod -R 755 /opt/v4call/data/certbot

'''Note:''' The app creates two separate SQLite databases in the logs directory:
* <code>v4call-ledger.db</code> — payment records (calls, ring fees, payouts). Only the server writes to this.
* <code>v4call-chat.db</code> — stored DMs and room messages. Separate from the ledger for security — if a bug in chat storage were exploited, the payment ledger remains untouched.

Federation also persists state in this directory:
* <code>approved-peers.json</code> — list of federation peer domains you've approved (created on first approval; survives container restarts).

== Step 11: Build and Start the Server ==

cd /opt/v4call
docker compose up -d --build

The first build downloads dependencies and takes 2-4 minutes. Check the status:

docker compose ps

You should see:

<pre>
NAME STATUS
v4call-app Up (healthy)
v4call-nginx Up
</pre>

Check the app started correctly:

docker compose logs app

Look for:

<pre>
[ledger] SQLite ready: /app/logs/v4call-ledger.db
[chat] SQLite ready: /app/logs/v4call-chat.db
v4call server running on 0.0.0.0:3000
[config] Server: yourcallapp (call.yourdomain.com)
[config] DM retention: 33 days | Room retention: 33 days | DM preview: 1
✓ Escrow key verified — matches @yourescrowaccount active key
✓ Escrow account @yourescrowaccount balance: 0.000 HBD
</pre>

If you see <code>SqliteError: unable to open database file</code> — run the chown command from Step 10 again then <code>docker compose restart app</code>.

Test HTTP is working:

curl http://call.yourdomain.com/debug-state

Should return: <code>{"lobbyUsers":[],"rooms":[]}</code>

If you can see the site in a browser over HTTP at this point — everything is working and ready for the certificate.

== Step 12: Get Your SSL Certificate ==

'''Before running certbot''', verify DNS and the challenge path are both working:

# Check DNS points to this server
nslookup call.yourdomain.com

# Test the challenge path
echo "test" > /opt/v4call/data/certbot/www/.well-known/acme-challenge/testfile
curl http://call.yourdomain.com/.well-known/acme-challenge/testfile

The curl command must return <code>test</code>. If it does not, Nginx is not running — check <code>docker compose ps</code> and <code>docker compose logs nginx</code>.

When both work, get the certificate. The <code>--entrypoint certbot</code> flag is required — without it, Docker runs the container's default renewal loop instead of the certonly command:

docker compose run --rm \
--entrypoint certbot \
certbot certonly \
--webroot \
-w /var/www/certbot \
-d call.yourdomain.com \
--email your@email.com \
--agree-tos \
--no-eff-email

Replace <code>call.yourdomain.com</code> with your domain and <code>your@email.com</code> with your email.

Success looks like:

<pre>
Requesting a certificate for call.yourdomain.com

Successfully received certificate.
Certificate is saved at: /etc/letsencrypt/live/call.yourdomain.com/fullchain.pem
Key is saved at: /etc/letsencrypt/live/call.yourdomain.com/privkey.pem
This certificate expires on 2026-07-09.
</pre>

Verify the files exist on the host:

ls /opt/v4call/data/certbot/conf/live/call.yourdomain.com/

Should show: <code>cert.pem chain.pem fullchain.pem privkey.pem README</code>

== Step 13: Enable HTTPS in Nginx ==

Now the certificate exists, update Nginx to serve HTTPS.

nano /opt/v4call/nginx/v4call.conf

Replace everything with the full HTTPS config:

<pre>
# HTTP — only used for certbot challenge and redirect to HTTPS
server {
listen 80;
server_name call.yourdomain.com www.call.yourdomain.com;

location /.well-known/acme-challenge/ {
root /var/www/certbot;
}

location / {
return 301 https://$host$request_uri;
}
}

# HTTPS — main app
server {
listen 443 ssl;
server_name call.yourdomain.com www.call.yourdomain.com;

# CHANGE PATH: ssl certs path uses your domain — find with: ls data/certbot/conf/live/
ssl_certificate /etc/letsencrypt/live/call.yourdomain.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/call.yourdomain.com/privkey.pem;

ssl_protocols TLSv1.2 TLSv1.3;
ssl_prefer_server_ciphers off;

add_header Strict-Transport-Security "max-age=63072000" always;
add_header X-Frame-Options DENY;
add_header X-Content-Type-Options nosniff;

# When user cancels the basic-auth login prompt, send them here
error_page 401 /info.html;

# info.html is served directly by Nginx — no auth, no proxy
location = /info.html {
root /usr/share/nginx/html;
auth_basic off;
}

# WebSocket — main client traffic
location /socket.io/ {
# Uncomment below to require username/password to enter site (testing only).
# See "Optional: Password Protect Your Server During Testing" section for setup.
#auth_basic "v4call — Private Testing";
#auth_basic_user_file /etc/nginx/.htpasswd;

proxy_pass http://app:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_cache_bypass $http_upgrade;
proxy_read_timeout 86400;
}

# Federation WebSocket — server-to-server, NEVER auth-protected.
# Peer v4call servers connect here to exchange presence/DMs/call invites.
# Trust validation happens inside the Node app (signed verify.json check
# + operator approval via /admin-peers.html). Do not add basic auth here —
# it would block all federation.
location /federation {
proxy_pass http://app:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_read_timeout 86400;
}

# Everything else — main HTTP traffic
location / {
# Uncomment below to require username/password to enter site (testing only).
#auth_basic "v4call — Private Testing";
#auth_basic_user_file /etc/nginx/.htpasswd;

proxy_pass http://app:3000;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_read_timeout 300;
proxy_send_timeout 300;
}

# Logs failed and successful login attempts when .htpasswd is enabled
error_log /var/log/nginx/error.log warn;
access_log /var/log/nginx/access.log;
}
</pre>

* REPLACE <code>call.yourdomain.com</code> with your domain throughout (it appears 4 times — server_name lines and ssl_certificate paths).
* The <code>auth_basic</code> lines are '''commented out by default''' so federation and normal users work out-of-box. To enable password protection for private testing, see [[#Optional:_Password_Protect_Your_Server_During_Testing|the Optional section]] below — it shows how to uncomment them and create users.
* '''Never''' add <code>auth_basic</code> to the <code>/federation</code> block — it would block all peer v4call servers from connecting to you.

Save and restart Nginx:

docker compose restart nginx

Check the logs — you should see '''no''' <code>[emerg]</code> errors:

docker compose logs nginx

The last lines should show:

<pre>
nginx/1.x.x ...
start worker processes
</pre>

* If you see an error such as:
<pre>[emerg] 1#1: cannot load certificate "/etc/letsencrypt/live/call.yourdomain.com/fullchain.pem": BIO_new_file() failed (SSL: error:80000002:system library::No such file or directory:calling fopen(/etc/letsencrypt/live/call.yourdomain.com/fullchain.pem, r) error:10000080:BIO routines::no such file)</pre>

* Make sure you edited <code>nginx/v4call.conf</code> correctly.
* To find the path for your SSL certs look in path <code>data/certbot/conf/live/</code>
* There are 4 lines to check in <code>nginx/v4call.conf</code>:
** <code>server_name call.yourdomain.com www.call.yourdomain.com;</code> (HTTP block)
** <code>server_name call.yourdomain.com www.call.yourdomain.com;</code> (HTTPS block)
** <code>ssl_certificate /etc/letsencrypt/live/call.yourdomain.com/fullchain.pem;</code>
** <code>ssl_certificate_key /etc/letsencrypt/live/call.yourdomain.com/privkey.pem;</code>
* When done restart nginx with: <code>docker compose restart nginx</code>

== Step 14: Set Up SSL Auto-Renewal ==

Let's Encrypt certificates expire after 90 days. A cron job renews them automatically.

crontab -e

Add this line at the bottom:

0 3 * * * cd /opt/v4call && docker compose run --rm --entrypoint certbot certbot renew --quiet && docker compose exec nginx nginx -s reload

Save and exit. This runs at 3am every day, renews if the cert is close to expiry, and reloads Nginx to pick up the new certificate.

== Step 15: Test Everything is Working ==

Test HTTPS:

curl https://call.yourdomain.com/debug-state

Should return: <code>{"lobbyUsers":[],"rooms":[]}</code>

Test admin access:

curl "https://call.yourdomain.com/admin/balance?key=YOUR_ADMIN_KEY"

Should return your escrow account balance.

Open your browser and go to <code>https://call.yourdomain.com</code>

You should see the v4call login page with:
* A padlock icon in the browser address bar
* A green '''⚡ Sign in with Keychain''' button (if Hive Keychain is installed)
* A manual posting key login option below it
* A '''📖 New here? Learn the v4call basics →''' link at the bottom

Log in with Hive Keychain or a posting key to confirm the login flow works. 🎉

== Step 16: Set Up Your Call Rates on Hive ==

For callers to be charged when they ring you, publish your rates on the Hive blockchain:

# Make sure Hive Keychain is installed in your browser
# Go to <code>https://call.yourdomain.com/rate-editor.html</code>
# Enter your Hive username
# Set your rates — ring fee, connect fee, duration rate per hour, minimum credit deposit
# Set <code>PLATFORM-FEE</code> to at least your server's <code>DEFAULT_PLATFORM_FEE</code> percentage (e.g. <code>10</code> for 10%). If you set it lower, paid contacts to your account will be rejected on this server.
# Optionally add custom token sections (e.g. <code>[TOKEN:CNOOBS]</code>) to offer discounted rates for callers who hold your token
# Click '''Generate''' to preview the rates block
# Click '''Post to Hive''' — Keychain will ask you to approve the post

This creates a post titled <code>v4call-rates</code> on your Hive blog. Your server reads this post automatically.

To verify your server read the rates correctly:

https://call.yourdomain.com/debug-rates/yourusername

To test with a specific caller (checks their token balances too):

https://call.yourdomain.com/debug-rates/yourusername?caller=theirusername&type=voice

You should see your rates as JSON, including which currency and rates apply for that caller.

== Step 17: Federation Setup (Optional) ==

If you want your server to talk to other v4call servers — so users on different servers can call/DM each other — set up federation. This is optional. A standalone server works fine without it.

Federation has two trust steps:

# '''Domain proof''' — you publish a signed JSON file at <code>https://yourdomain.com/.well-known/v4call-server.json</code> proving that your Hive account controls this domain
# '''Directory listing''' — you publish a Hive post tagged <code>v4call-server</code> announcing your server exists, so other operators can discover you

'''Important escrow rule''': the <code>ESCROW_ACCOUNT</code> in your <code>.env</code> must match the <code>ESCROW:</code> field in your users' rates posts. The active key for that escrow has to live on '''this''' server. If a user's rates post points at a different escrow than what your server holds the key for, paid calls/DMs to that user will fail (your server can't disburse from an escrow it doesn't control).

=== Step 17a: Generate and Host the Verify File ===

# Open <code>https://yourdomain.com/server-sign.html</code> in a browser with Hive Keychain installed
# Fill in: Hive account (same as <code>SERVER_HIVE_ACCOUNT</code>), domain, escrow account, fee account, federation WS URL (<code>wss://yourdomain.com/federation</code>)
# Click '''⚡ Sign with Hive Keychain'''
# Click '''⬇ Download''' — saves <code>v4call-server.json</code>
# Upload to your server, replacing the placeholder file. From your local machine:
scp v4call-server.json root@yourvps:/opt/v4call/public/.well-known/

(Or use any other transfer method you prefer — SFTP client, paste via SSH, etc.)

Verify it's served:
curl https://yourdomain.com/.well-known/v4call-server.json

You should see your signed JSON. If you see <code>404</code>, check the file is at exactly <code>public/.well-known/v4call-server.json</code> — the directory uses a '''hyphen''', not an underscore (RFC 8615), and the filename must be exactly <code>v4call-server.json</code>.

Rebuild so the file is baked into the Docker image:
docker compose down && docker compose build --no-cache && docker compose up -d

'''Tip''': commit the generated file to your git repo so future fresh installs include it automatically. It contains only public data — safe to commit. The placeholder shipped in the repo is overwritten by your file.

=== Step 17b: Announce on Hive ===

For other operators to discover you, publish a Hive post advertising your server:

# After signing in Step 17a, click the '''📡 Announce on Hive →''' link on the signer output card (auto-fills the announce page)
# Or open <code>https://yourdomain.com/server-announce.html</code> directly
# Confirm the prefilled values
# Click '''📡 Post to Hive''' — Keychain will broadcast the post

The post lives forever on Hive. If your config changes, just post a new one — the most recent post per Hive account wins. No need to delete old posts (Hive posts are effectively permanent anyway).

=== Step 17c: Connect to Known Peers (Manual Mode) ===

Skip the discovery step and go straight to a known peer by adding their WebSocket URL to <code>FEDERATION_PEERS</code> in <code>.env</code>:
FEDERATION_PEERS=wss://otherserver.com/federation

Both servers must list each other. Rebuild after editing <code>.env</code>:
docker compose down && docker compose build --no-cache && docker compose up -d

Servers in <code>FEDERATION_PEERS</code> are auto-approved on startup — they bypass the manual approval step.

=== Step 17d: Discover and Approve Peers (Auto Mode) ===

Your server scans Hive for <code>v4call-server</code> posts on startup and every 2 hours. Discovered peers are NOT auto-connected — you must approve each one.

# Open <code>https://yourdomain.com/admin-peers.html</code>
# Paste your <code>ADMIN_KEY</code> (from <code>.env</code>) and click '''🔄 Load / Refresh'''
# Each discovered peer shows a card with verification status, escrow, fee account, post age
# Click '''✓ Approve''' to add them to your federation
# Click '''✗ Revoke''' to remove an approved peer

Approvals persist to <code>/app/logs/approved-peers.json</code> so they survive container restarts.

=== Federation Health Check ===

Watch the federation logs:
docker compose logs -f app | grep -E "\[federation\]|\[discovery\]|\[peers\]"

Healthy startup looks like:

<pre>
[federation] Approved peers: peer-domain.com
[federation] Connecting to wss://peer-domain.com/federation...
[federation] Outbound connected: wss://peer-domain.com/federation
[federation] ✓ Peer verified: @peer-domain.com (signer: @peer-account, escrow: @peer-escrow)
[discovery] Hive returned 2 post(s) under v4call-server tag
[discovery] Scan complete — 2 v4call-server post(s), 2 verified
</pre>

When a user logs in on either server, you should see:

<pre>
[federation] → user-online @username → 1 peer(s) (on their home server)
[federation] ← user-online @username@theirhome.com (on your server)
</pre>

== Feature Guide: What Your Server Can Do ==

This section explains all the features available in v4call and how they work. No code changes needed — everything described here is built in and ready to use.

=== Login Options ===

v4call supports two ways to sign in:

* '''Hive Keychain''' (recommended) — click the green '''⚡ Sign in with Keychain''' button. Keychain signs a challenge to prove your identity. No key paste needed. After login, a 🔑 panel appears in the lobby where you can optionally enter your posting key to unlock encrypted messaging (Keychain cannot expose private keys, so encryption needs the key entered once per session).
* '''Manual posting key''' — paste your Hive posting private key (starts with <code>5J</code>) directly. The key stays in browser session memory only — never sent to the server.

Both methods verify your identity against the Hive blockchain.

=== Voice and Video Calls ===

Each online user in the lobby shows three action buttons:

* '''📞 Green phone icon''' — start a '''voice-only''' call (audio, no camera)
* '''🎥 Blue camera icon''' — start a '''video''' call (audio + camera)
* '''💬 Purple chat bubble icon''' — open the '''DM panel''' to send a direct message

Voice calls request microphone only — no camera permission prompt. Video calls request both. The caller and callee can have different call types — the type is set by whoever initiates the call.

Separate rates can be set for voice and video calls in the rates post (voice is typically cheaper).

Federated users (on a different v4call server) appear in the lobby with a small server-domain badge under their username. The call/DM buttons work the same — federation routing is transparent.

=== Direct Messages (DMs) ===

Click the purple 💬 button next to any online user to open the DM panel. DMs are end-to-end encrypted using Hive posting keys — the server stores only ciphertext it cannot read.

'''Chat storage:''' DMs are stored on the server in an encrypted database (<code>v4call-chat.db</code>) for up to <code>DM_RETENTION_DAYS</code> (default: 33 days). Both sender and recipient get their own encrypted copy stored, so both can retrieve their history later.

'''Unread alerts:''' When you log in, if you have unread DMs, a popup appears showing how many messages from how many users. Click a username in the popup to open their DM history.

'''DM previews:''' The last <code>DM_PREVIEW_COUNT</code> messages per conversation are loaded into the lobby chat on login, so you can see recent activity at a glance. Set to <code>0</code> in <code>.env</code> to disable.

'''Full history:''' Click the DM button for any user to load the complete conversation history, shown between "— DM history —" dividers.

=== Rooms ===

Users can create private rooms by selecting users in the lobby (toggle switch) and clicking '''Create & Invite'''. Rooms support encrypted messaging, video, and voice.

'''Room history:''' When a new user joins a room, they see past messages — broadcasts in full, encrypted messages only if they were addressed to them. A "— earlier messages —" divider separates history from live messages.

'''Ephemeral rooms:''' A warning banner at the top of every room says: "⚠ Room is ephemeral — if all users leave, the room and its history are deleted. New members can only read messages encrypted to their key." When the last person leaves a room, all stored messages for that room are deleted from the database.

=== Custom Token Payments (Hive-Engine) ===

v4call supports payment in any Hive-Engine token, not just HBD. This is configured per-user in their rates post using <code>[TOKEN:SYMBOL]</code> sections.

'''How it works:'''
# A user (e.g. @cnoobz) creates a custom token on Hive-Engine (e.g. CNOOBS)
# In their rates post, they add a <code>[TOKEN:CNOOBS]</code> section with lower rates than their default HBD rates
# When a caller who holds CNOOBS contacts @cnoobz, the server detects the token balance and offers the token rates
# If the caller holds multiple qualifying tokens, '''all options are shown''' in a currency picker — the caller chooses which to pay with
# The payment goes through Hive Keychain as a <code>custom_json</code> Hive-Engine transfer

'''For the escrow account:''' Your escrow account needs to hold some of each custom token that users on your server accept. Token payouts (to the callee) and refunds (to the caller) are sent from the escrow account's token balance, just like HBD.

'''Payment picker:''' When multiple payment options exist (e.g. CNOOBS at 1 per message, HBD at 100000 per message), the payment modal shows clickable currency buttons so the caller can see all rates and choose the best option.

=== Platform Fee System ===

The platform fee is how your server earns revenue from paid calls and DMs.

'''How it works:'''
* Your server's <code>DEFAULT_PLATFORM_FEE</code> in <code>.env</code> is the '''minimum''' percentage your server accepts (e.g. <code>10</code> = 10%)
* Each user sets <code>PLATFORM-FEE</code> in their Hive rates post — this is the maximum fee they are willing to pay to a server
* If the user's posted fee is '''lower''' than your server's minimum → '''rejected'''. The caller sees a message explaining the mismatch, and the callee is told to raise their fee.
* If the user's posted fee '''meets or exceeds''' your server's minimum → '''accepted''', and '''the server charges its own rate''' (the minimum), not the user's higher number. The callee gets the best price.
* If the user has '''no <code>PLATFORM-FEE</code> line''' in their rates post → the server's default is used automatically. No mismatch.
* '''Free contacts''' (no payment involved) are never affected by fee enforcement.

'''Why this matters for federation:''' Different servers can set different platform fees. Users can shop around — pick a server with a fee they find agreeable. This creates a free market for server operators.

'''Example:'''
* Your server: <code>DEFAULT_PLATFORM_FEE=3</code> (3%)
* @alice posts: <code>PLATFORM-FEE: 5%</code> → accepted, server charges 3% (best price for alice)
* @bob posts: <code>PLATFORM-FEE: 1%</code> → rejected, bob needs to raise to at least 3%
* @charlie has no fee line → defaults to 3%, automatically accepted

=== Federation ===

Federation lets users on different v4call servers see, call, and DM each other. Each server independently:

* Holds its own escrow account (the active key never leaves the server it belongs to)
* Verifies and disburses payments through its own escrow
* Takes the platform fee for calls/DMs received by its own users

Cross-server payments work like this: caller pays the callee's escrow on Hive (read from the callee's rates post), the callee's server verifies the payment on-chain and forwards a notification, both servers exchange call/DM signalling, and the callee's server disburses callee-net + platform-fee from its own escrow at call end (with refunds going cross-server back to the caller as a normal Hive transfer).

WebRTC media stays peer-to-peer — neither server sees the audio/video.

See [[#Step_17:_Federation_Setup_(Optional)|Step 17: Federation Setup]] for the setup steps.

== Admin Configuration Reference ==

All settings are in the <code>.env</code> file. After changing any value, rebuild:

docker compose down && docker compose build --no-cache && docker compose up -d

{| class="wikitable"
|-
! Variable !! Default !! Description
|-
| <code>SERVER_NAME</code> || <code>v4call</code> || Display name for your server
|-
| <code>SERVER_DOMAIN</code> || <code>v4call.com</code> || Your server's domain
|-
| <code>SERVER_HIVE_ACCOUNT</code> || <code>v4call</code> || Hive account that receives platform fees (and signs your federation verify file)
|-
| <code>ESCROW_ACCOUNT</code> || <code>v4call-escrow</code> || Hive account that holds funds during calls. The active key for this account must live on '''this''' server.
|-
| <code>V4CALL_ESCROW_KEY</code> || ''(none)'' || Active private key for the escrow account. '''Required.'''
|-
| <code>ADMIN_KEY</code> || ''(none)'' || Password for admin endpoints (<code>/admin/balance</code>, <code>/admin/ledger</code>, <code>/admin/peers</code>)
|-
| <code>DEFAULT_PLATFORM_FEE</code> || <code>10</code> || Server's minimum platform fee percentage
|-
| <code>FEDERATION_PEERS</code> || ''(blank)'' || Comma-separated peer WebSocket URLs (e.g. <code>wss://peer.com/federation</code>). Listed peers are auto-approved on startup. Blank = standalone mode.
|-
| <code>DM_RETENTION_DAYS</code> || <code>33</code> || Days to keep stored DMs before cleanup
|-
| <code>ROOM_RETENTION_DAYS</code> || <code>33</code> || Days to keep stored room messages before cleanup
|-
| <code>DM_PREVIEW_COUNT</code> || <code>1</code> || Recent DMs per conversation shown on login (0 = off)
|-
| <code>HIVE_API</code> || ''(blank)'' || Override primary Hive API node. Blank = auto-select from built-in list
|-
| <code>MAX_CALL_DURATION_MIN</code> || <code>120</code> || Maximum call length in minutes before auto-disconnect
|-
| <code>CALL_COOLDOWN_MS</code> || <code>30000</code> || Milliseconds between call attempts to same user
|-
| <code>PAYMENT_VERIFY_RETRIES</code> || <code>3</code> || Number of attempts to verify a blockchain payment
|-
| <code>PAYMENT_VERIFY_DELAY_MS</code> || <code>5000</code> || Delay between verification retry attempts
|}

=== Debug & Admin Endpoints ===

These are useful for testing without making actual calls:

* <code>/debug-state</code> — shows current lobby users and active rooms (no auth required)
* <code>/debug-rates/USERNAME</code> — shows parsed rates for a user
* <code>/debug-rates/USERNAME?caller=CALLER&type=voice</code> — shows what rates a specific caller would receive (checks token balances too)
* <code>/admin/balance?key=YOUR_ADMIN_KEY</code> — shows escrow account HBD balance
* <code>/admin/ledger?key=YOUR_ADMIN_KEY</code> — shows recent payment records
* <code>/admin/peers?key=YOUR_ADMIN_KEY</code> — JSON list of discovered + approved federation peers
* <code>/admin/peers/approve?key=YOUR_ADMIN_KEY&domain=peer.com</code> (POST) — approve a discovered peer
* <code>/admin/peers/revoke?key=YOUR_ADMIN_KEY&domain=peer.com</code> (POST) — revoke approval
* <code>/admin/peers/rescan?key=YOUR_ADMIN_KEY</code> (POST) — force a Hive directory rescan

=== Operator Tool Pages ===

* <code>/rate-editor.html</code> — generate your <code>v4call-rates</code> Hive post
* <code>/server-sign.html</code> — generate your signed federation verify file
* <code>/server-announce.html</code> — publish your server announcement on Hive
* <code>/admin-peers.html</code> — UI for federation peer approve/revoke/rescan
* <code>/info.html</code> — public landing page (shown to users who hit the basic-auth login cancel)

== Updating Your Server ==

'''Important:''' Always use <code>docker compose down</code> before rebuilding. Without this step, Docker may reuse the old container even after a rebuild, and your changes will not take effect.

cd /opt/v4call
docker compose down
docker compose build --no-cache
docker compose up -d

Your data, SQLite databases and <code>.env</code> config are preserved — they live in <code>data/logs/</code> which is a mounted volume.

To pull updates from GitHub and deploy:

cd /opt/v4call
git pull
docker compose down
docker compose build --no-cache
docker compose up -d

To push your own customisations to GitHub:

# On your local computer after making changes:
git add .
git commit -m "describe what you changed"
git push

# On the VPS:
cd /opt/v4call
git pull
docker compose down
docker compose build --no-cache
docker compose up -d

== Common Problems and Fixes ==

=== Changes not showing after rebuild ===

If you edited <code>server.js</code> or <code>index.html</code> but changes are not visible, you probably forgot to bring Docker down first. <code>docker compose restart</code> and even <code>docker compose up -d --build</code> can reuse old containers.

'''Fix:'''

docker compose down
docker compose build --no-cache
docker compose up -d

=== SqliteError: unable to open database file ===

The app container runs as UID 1000 but the logs directory was created by root. Fix:

chown -R 1000:1000 /opt/v4call/data/logs
docker compose restart app

=== Certbot says "No renewals were attempted" ===

The certbot container's default behaviour is a renewal loop. Your <code>certonly</code> command is being ignored. Always use <code>--entrypoint certbot</code> to override it:

docker compose run --rm --entrypoint certbot certbot certonly ...

Without <code>--entrypoint certbot</code> the container runs its renewal script instead of your command.

=== Nginx crashes with "cannot load certificate: No such file" ===

You added the HTTPS server block before getting the certificate. Nginx reads all server blocks at startup — if the cert file doesn't exist, the entire process fails.

Fix: revert nginx config to HTTP-only (Step 9), restart Nginx, get the certificate (Step 12), then re-add HTTPS (Step 13).

=== Webroot challenge test returns nothing ===

Nginx is not running. Check:

docker compose ps
docker compose logs nginx

If Nginx is restarting — it has the HTTPS config with a missing cert file. Use the HTTP-only config.

=== "Escrow key does NOT match" warning on startup ===

The key in <code>.env</code> is the wrong type. You need the '''active''' private key, not the posting or owner key. Find it in your Hive wallet → Keys & Permissions → Active. It starts with <code>5K</code>.

=== Site unreachable on port 443 ===

Check that the certificate was issued:

ls /opt/v4call/data/certbot/conf/live/

Should show a folder with your domain name. If empty — go back to Step 12.

=== npm ci error during Docker build ===

The <code>npm ci</code> command requires a <code>package-lock.json</code> file. The project uses <code>npm install</code> instead. If you see this error, check your <code>Dockerfile</code> — it should say <code>npm install</code> not <code>npm ci</code>.

=== Custom token payments not working ===

If token rates are detected but payments fail:
* Check the escrow account holds the token — send some tokens to your escrow account on Hive-Engine
* Check the token symbol matches exactly (case-sensitive) between the rates post and Hive-Engine
* Check the server logs: <code>docker compose logs app | grep -i "token\|cnoobs\|escrow-token"</code>
* The Hive-Engine API endpoint must be <code>https://api.hive-engine.com/rpc/contracts</code> — this is built into the code

=== [encrypted — unlock with 🔑 key panel to read] ===

You logged in with Hive Keychain. Keychain does not expose private keys, so encrypted messages cannot be decrypted without your posting key. Enter your posting key in the 🔑 panel at the bottom of the online users list. The key stays in browser session memory only — it is needed once per session.

=== Federation peer verification fails with HTTP 404 ===

Logs show:
[federation] ✗ Peer verification failed for X: Cannot fetch verify.json: HTTP 404

The peer's <code>/.well-known/v4call-server.json</code> file isn't being served. Common causes:

* '''Wrong directory name''' — must be <code>.well-known</code> with a hyphen, not <code>.well_known</code> with an underscore (RFC 8615).
* '''Wrong filename''' — must be <code>v4call-server.json</code>, not <code>verify.json</code> or anything else. The verifier code looks for this exact name.
* '''Not in the Docker image''' — file lives at <code>public/.well-known/v4call-server.json</code> in the repo and is copied into the image at build time. After placing the file, rebuild: <code>docker compose down && docker compose build --no-cache && docker compose up -d</code>.
* '''Placeholder not replaced''' — the repo ships with a tiny placeholder. You must overwrite it with your own signed file from <code>/server-sign.html</code> before federation will work.

Test from outside the container:
curl https://yourdomain.com/.well-known/v4call-server.json

Should return your signed JSON, not <code>404</code> or the placeholder.

=== Federation connection flapping (rapid disconnect/reconnect loop) ===

If logs show repeated <code>Outbound connected</code> followed by <code>Disconnected — retry in 2s</code> with no successful handshake, check verify.json:

* Is the file present at the path above?
* Does its <code>signature</code> match the Hive account's posting key? Test by pasting the JSON into the '''Verify''' panel on <code>/server-sign.html</code> — should say "✓ Signature valid".
* Does <code>hive_account</code> in the JSON match <code>SERVER_HIVE_ACCOUNT</code> in the peer's .env? They must match.

=== Federation peer connects but my user can't be seen on the other side ===

If two servers connect successfully but a user on Server A doesn't appear in Server B's lobby, check:

* Server A logs: <code>[federation] → user-online @username → 1 peer(s)</code> — confirms A broadcast the presence
* Server B logs: <code>[federation] ← user-online @username@A.com</code> — confirms B received it

If A logs the broadcast but B never received it, the federation socket might be one-way. Check both servers have approved each other (visible at <code>/admin-peers.html</code>).

=== Federated paid call/DM fails silently after payment ===

Most common cause: the user's <code>v4call-rates</code> post declares an <code>ESCROW:</code> account whose active key isn't on their home server. The caller's payment lands in that escrow correctly, but no server can disburse from it.

Fix: have the user re-post their rates with an <code>ESCROW:</code> matching their home server's <code>ESCROW_ACCOUNT</code> in <code>.env</code>. Or migrate that escrow account's active key to the right server.

The federation handshake also surfaces this as a clear error message via the escrow-mismatch guard — check the caller-side server logs for it.

=== Discovery scanner finds 0 posts ===

If <code>/admin-peers.html</code> shows "No v4call-server posts discovered yet" even after rescanning:

* Click '''🔍 Rescan Hive now''' and watch logs: <code>docker compose logs -f app | grep discovery</code>
* Expected: <code>[discovery] Hive returned N post(s) under v4call-server tag</code>
* If N = 0, no Hive posts exist with that tag yet — publish your own via <code>/server-announce.html</code>
* If you see <code>[discovery] No response from Hive tag query</code>, the Hive API is unreachable from inside the container. Test container DNS / outbound HTTPS by hitting any external HTTPS URL from the container.

== Quick Reference ==

{| class="wikitable"
|-
! Command !! What it does
|-
| <code>docker compose ps</code> || Show status of all containers
|-
| <code>docker compose logs app</code> || Show app logs
|-
| <code>docker compose logs nginx</code> || Show Nginx logs
|-
| <code>docker compose logs -f app</code> || Watch live logs (Ctrl+C to stop)
|-
| <code>docker compose down</code> || Stop everything ('''always do this before rebuilding''')
|-
| <code>docker compose build --no-cache</code> || Rebuild without using cached layers
|-
| <code>docker compose up -d</code> || Start everything in background
|-
| <code>docker compose down && docker compose build --no-cache && docker compose up -d</code> || Full rebuild cycle (use after any code change)
|-
| <code>docker compose restart nginx</code> || Restart Nginx after config-only changes (no rebuild needed)
|-
| <code>chown -R 1000:1000 /opt/v4call/data/logs</code> || Fix SQLite write permissions
|-
| <code>docker compose run --rm --entrypoint certbot certbot certificates</code> || List SSL certificates
|-
| <code>curl http://yourdomain.com/.well-known/acme-challenge/testfile</code> || Test certbot webroot works
|-
| <code>docker compose logs app | grep -i "token\|escrow"</code> || Check token payment logs
|-
| <code>docker compose logs -f app | grep -E "\[federation\]|\[discovery\]"</code> || Watch federation activity
|-
| <code>curl https://yourdomain.com/.well-known/v4call-server.json</code> || Check verify file is served
|-
| <code>https://yourdomain.com/server-sign.html</code> || Generate signed federation verify file
|-
| <code>https://yourdomain.com/server-announce.html</code> || Publish server to Hive directory
|-
| <code>https://yourdomain.com/admin-peers.html</code> || Manage federation peer approvals
|}

== Optional: Password Protect Your Server During Testing ==

<div class="toccolours mw-collapsible mw-collapsed">
<strong>Optional: Password Protect Your Server During Testing (HTTP Basic Auth)</strong>
<div class="mw-collapsible-content">

During development and testing you may want to restrict access so only people you invite can use your server. This uses Nginx HTTP Basic Auth — a simple username and password prompt that appears before the v4call login screen.

When a visitor cancels the login prompt they are shown a public <code>info.html</code> page where they can read about the project and request access.

'''Important''': do NOT add basic auth to the <code>/federation</code> location block. Federation peers cannot supply HTTP credentials and the connection will fail. The auth lines below are added only to <code>/socket.io/</code> and <code>/</code>.

*<b> Step 1 — Install the htpasswd tool</b>

<code>apt install -y apache2-utils</code>

*<b> Step 2 — Create the password file and add your first user </b>

<code>htpasswd -c /opt/v4call/nginx/.htpasswd yourusername</code>

You will be prompted to enter and confirm a password. The <code>-c</code> flag creates the file. Do not use <code>-c</code> again or it will overwrite the file and delete existing users.

To add more users later:

<code>htpasswd /opt/v4call/nginx/.htpasswd anotherusername</code>

To remove a user:

<code>htpasswd -D /opt/v4call/nginx/.htpasswd username</code>

*<b> Step 3 — Create the public info page </b>

<code>nano /opt/v4call/public/info.html</code>

Paste your HTML content — a page explaining the project and how to request access. This page is served publicly without a password so visitors who cancel the login prompt can still read it.

*<b> Step 4 — Mount the files into the Nginx container </b>

Edit <code>docker-compose.yml</code> and add two lines to the nginx volumes section:

<pre>
nginx:
volumes:
- ./nginx/v4call.conf:/etc/nginx/conf.d/default.conf:ro
- ./nginx/.htpasswd:/etc/nginx/.htpasswd:ro # add this
- ./public/info.html:/usr/share/nginx/html/info.html:ro # add this
- ./data/certbot/conf:/etc/letsencrypt:ro
- ./data/certbot/www:/var/www/certbot:ro
</pre>

*<b> Step 5 — Enable auth in your Nginx config </b>

The HTTPS config from Step 13 already includes the <code>auth_basic</code> lines, just commented out. Open <code>nginx/v4call.conf</code> and uncomment them in BOTH the <code>/socket.io/</code> and <code>/</code> location blocks (4 lines total, two pairs):

<pre>
auth_basic "v4call — Private Testing";
auth_basic_user_file /etc/nginx/.htpasswd;
</pre>

'''Do not''' uncomment auth in the <code>/federation</code> block — leave it as-is.

*<b> Step 6 — Recreate the Nginx container to pick up the new volume mounts </b>

'''Important''': <code>docker compose restart nginx</code> is not enough — it reuses the old container and ignores new volume mounts. You must recreate it:

<code>docker compose down && docker compose up -d</code>

After this, verify the files are mounted inside the container:

<code>docker compose exec nginx ls /usr/share/nginx/html/</code>

You should see <code>info.html</code> listed alongside <code>50x.html</code> and <code>index.html</code>.

*<b> Step 7 — Test it works </b>

<code>curl -o /dev/null -s -w "%{http_code}" https://call.yourdomain.com/</code>

Should return <code>401</code> (login required).

<code>curl -o /dev/null -s -w "%{http_code}" https://call.yourdomain.com/info.html</code>

Should return <code>200</code> (public, no auth needed).

<code>curl -u youruser:yourpassword -o /dev/null -s -w "%{http_code}" https://call.yourdomain.com/</code>

Should return <code>200</code> (correct credentials accepted).

*<b> Managing users without restarting </b>

After adding or removing users from the <code>.htpasswd</code> file, reload Nginx config without downtime:

<code>docker compose exec nginx nginx -s reload</code>

No restart needed — Nginx re-reads the <code>.htpasswd</code> file on every request anyway.

*<b> Keep .htpasswd out of GitHub </b>

The password file should never be committed to your repository. It's already in the project's <code>.gitignore</code>, but if you forked, double-check:

<code>echo "nginx/.htpasswd" >> /opt/v4call/.gitignore</code>

*<b> Removing auth when you go public </b>

When you are ready to open your server to everyone, simply re-comment the <code>auth_basic</code> lines from <code>nginx/v4call.conf</code> and reload:

<code>docker compose exec nginx nginx -s reload</code>

No other changes needed.

</div>
</div>

<div class="toccolours mw-collapsible mw-collapsed">
'''How to check if anyone tried to log in (failed attempts) or successfully logged in with .htpasswd on Nginx in Docker'''

<div class="mw-collapsible-content">

'''Important Tip:''' Always run these commands in the same folder where your <code>docker-compose.yml</code> file is located. If you are in the wrong directory the commands will not find your container and nothing will show up.

* ''''' Basic Commands '''''

; '''See everything live (good while testing)'''
: <code>docker compose logs -f nginx</code><br>
: <code>-f</code> means "follow/live" – new log lines appear automatically. Remove <code>-f</code> if you only want to read the current logs once and stop.

; '''Best command to watch failed login attempts (people guessing passwords)'''
: <code>docker compose logs -f nginx | grep -E "mismatch|not found|401"</code>

; '''See who successfully logged in'''
: <code>docker compose logs nginx | grep "remote_user"</code>

; '''Combined view – most useful for daily checking (failed + successful)'''
: <code>docker compose logs -f --tail=100 nginx | grep -E "(mismatch|not found|remote_user|401)"</code>

* ''''' What the Logs Look Like '''''

'''Failed attempt (wrong password):'''
<pre>2026/04/17 01:23:45 [error] ... user "admin": password mismatch, client: 185.123.45.67, ...</pre>

'''Failed attempt (wrong username):'''
<pre>2026/04/17 01:24:12 [error] ... user "hacker123" was not found in "/etc/nginx/.htpasswd", client: 45.67.89.10, ...</pre>

'''Successful login:'''
<pre>... "GET /protected/ HTTP/1.1" 200 ... remote_user: "myuser" ...</pre>

* ''''' How to Customise These Commands '''''

* Change <code>nginx</code> to the exact name of your service if it is different in docker-compose.yml.
* Remove <code>-f</code> to read the full log once without live following.
* Change <code>--tail=100</code> to <code>--tail=500</code> (or any number) to show more or fewer old lines.
* Add or remove words in the <code>grep</code> part to filter differently.
Examples:
* Only failed attempts: <code>grep -E "mismatch|not found"</code>
* Only 401 errors: <code>grep " 401 "</code>
* Everything auth related: <code>grep -E "(auth|password|mismatch|not found|remote_user)"</code>

* '''''Quick Copy-Paste Commands '''''

# Watch failed guesses live
docker compose logs -f nginx | grep -E "mismatch|not found|401"

# Check successful logins
docker compose logs nginx | grep "remote_user"

# Combined quick check (recommended)
docker compose logs -f --tail=100 nginx | grep -E "(mismatch|not found|remote_user|401)"

</div>
</div>

[[Category:Docker]]
[[Category:Ubuntu]]
[[Category:Hive]]
[[Category:v4call]]
[[Category:WebRTC]]

Basic Html JavaScript POPUP warning Accept

2026-04-19T19:24:55Z

AwesomO: Created page with "3 parts ==Part one== * This is placed in the <head> </head> at the top of index.html contains css <pre> <style> #overlay { position: fixed; top: 0; left: 0; width: 100%; height: 100%; background: rgba(0,0,0,0.85); color: white; z-index: 10000; display: flex; align-items: center; justify-content: center; text-align: center; } .popup-box { background: #222; padding: 30px; border-radius: 10px; border: 1px solid #444; } button { padding: 10px 20px; curso..."

3 parts

==Part one==
* This is placed in the <head> </head> at the top of index.html contains css
<pre>
<style>
#overlay {
position: fixed; top: 0; left: 0; width: 100%; height: 100%;
background: rgba(0,0,0,0.85); color: white; z-index: 10000;
display: flex; align-items: center; justify-content: center; text-align: center;
}
.popup-box { background: #222; padding: 30px; border-radius: 10px; border: 1px solid #444; }
button { padding: 10px 20px; cursor: pointer; background: #007bff; color: white; border: none; border-radius: 5px; }
.hidden { display: none !important; }
</style>
</pre>

==part two==
* This is placed in/at the top of the <body> </body> section, contains message.
<pre>

<div id="overlay">
<div class="popup-box">
<h2>Welcome to Complete Noobs!</h2>
<p>We use cookies to track traffic. Are you 21 or older?</p>
<p>By accepting you are entering at your own risk</p>
<button onclick="acceptAndHide()">Yes, I Accept & I'm Over 21 & am aware you are noobs and are still learning i enter at my own risk</button>
<p>→ <a href="https://www.google.com" >No Thank You - take me to Google</a></p>
</div>
</div>
</pre>

==part 3==
* This is placed in/at the bottom of the <body> </body> section, contains js script.

<pre>

<script>
function acceptAndHide() {
// Save the choice in the browser's "localStorage" so it doesn't pop up again
localStorage.setItem('gate_passed', 'true');
document.getElementById('overlay').classList.add('hidden');
}

// On page load, check if they already clicked "Yes"
window.onload = function() {
if (localStorage.getItem('gate_passed') === 'true') {
document.getElementById('overlay').classList.add('hidden');
}
};
</script>
</pre>

==use case==
* Sample use case

<pre>
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>My Projects - Status Update</title>
<style>
body {
font-family: Arial, Helvetica, sans-serif;
max-width: 800px;
margin: 40px auto;
padding: 20px;
line-height: 1.6;
color: #333;
}
h1 {
text-align: center;
color: #222;
}
h2 {
color: #444;
border-bottom: 2px solid #eee;
padding-bottom: 8px;
}
a {
color: #0066cc;
text-decoration: none;
}
a:hover {
text-decoration: underline;
}
.status {
font-style: italic;
color: #555;
}
</style>

<style>
#overlay {
position: fixed; top: 0; left: 0; width: 100%; height: 100%;
background: rgba(0,0,0,0.85); color: white; z-index: 10000;
display: flex; align-items: center; justify-content: center; text-align: center;
}
.popup-box { background: #222; padding: 30px; border-radius: 10px; border: 1px solid #444; }
button { padding: 10px 20px; cursor: pointer; background: #007bff; color: white; border: none; border-radius: 5px; }
.hidden { display: none !important; }
</style>

</head>


<script async src="https://www.googletagmanager.com/gtag/js?id=G-YXYQE65XY1"></script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());

gtag('config', 'G-YXYQE65XY1');
</script>

<body>

<div id="overlay">
<div class="popup-box">
<h2>Welcome to Complete Noobs!</h2>
<p>We use cookies to track traffic. Are you 21 or older?</p>
<p>By accepting you are entering at your own risk</p>
<button onclick="acceptAndHide()">Yes, I Accept & I'm Over 21 & am aware you are noobs and are still learning i enter at my own risk</button>
<p>→ <a href="https://www.google.com" >No Thank You - take me to Google</a></p>
</div>
</div>

<h1>Project Status</h1>

<h2>CompleteNoobs</h2>
<p class="status">Currently on hold due to lack of free time.</p>
<p>It will be relaunched as <strong>cnoobs.com</strong> running inside a Docker container.</p>
<p>Future plans include a possible soft-fork of MediaWiki that allows Hive accounts holding a certain amount of CNOOBS coins to post and edit pages.
I'm also interested in integrating the Hive rewards system for content creators and exploring reward splits between users.</p>
<p>Additional custom features being considered:</p>
<ul>
<li>Custom tags for embedding IPFS content to keep the wiki database smaller and more portable:</li>
<ul>
<li><code><ipfs_video>ipfs_addr</ipfs_video></code></li>
<li><code><ipfs_pic>ipfs_addr</ipfs_pic></code></li>
<li><code><ipfs_audio>ipfs_addr</ipfs_audio></code></li>
<li><code><ipfs_file>ipfs_addr</ipfs_file></code></li>
</ul>
</ul>
<p>The old draft remains available but is unmaintained:</p>
<p>→ <a href="https://www.completenoobs.com/noobs/Main_Page" target="_blank">CompleteNoobs.com (old wiki)</a></p>
<p>→ <a href="https://xml.completenoobs.com" target="_blank">xml.CompleteNoobs.com (old xml downloads)</a></p>

<h2>n33b.com</h2>
<p class="status">Currently on hold.</p>
<p>It will <strong>not</strong> become a coin project. It will return to its original purpose: a purely educational site for people who like to learn by tinkering and hands-on experimentation.</p>

<h2>v4call.com</h2>
<p>→ <a href="https://v4call.com" target="_blank">v4call.com</a></p>
<p class="status">idk — tinker gonna tinker 😄</p>

<hr>
<p style="text-align:center; color:#777; font-size:0.9em;">
Last updated: April 2026
</p>

<script>
function acceptAndHide() {
// Save the choice in the browser's "localStorage" so it doesn't pop up again
localStorage.setItem('gate_passed', 'true');
document.getElementById('overlay').classList.add('hidden');
}

// On page load, check if they already clicked "Yes"
window.onload = function() {
if (localStorage.getItem('gate_passed') === 'true') {
document.getElementById('overlay').classList.add('hidden');
}
};
</script>

</body>
</html>
</pre>

V4CALL

2026-04-19T14:17:40Z

AwesomO: Created page with "{{:LICENCE_HEADER_MIT}} = v4call — Deploy Your Own Server on Ubuntu 24.04 with Docker = From CompleteNoobs This guide walks through deploying your own v4call server from scratch on a fresh Vultr Ubuntu 24.04 VPS — from first login to a working HTTPS video/audio calling service on your own domain. v4call is an open-source, decentralised video and audio calling platform that uses Hive blockchain for identity and HBD micropayments. It supports custom Hive-Engine to..."

{{:LICENCE_HEADER_MIT}}

= v4call — Deploy Your Own Server on Ubuntu 24.04 with Docker =

From CompleteNoobs

This guide walks through deploying your own v4call server from scratch on a fresh Vultr Ubuntu 24.04 VPS — from first login to a working HTTPS video/audio calling service on your own domain.

v4call is an open-source, decentralised video and audio calling platform that uses Hive blockchain for identity and HBD micropayments. It supports custom Hive-Engine token payments, encrypted direct messages with persistent chat history, voice-only and video calls, and a free-market platform fee system. Fork it, run your own server, keep all your platform fees, join the federation, federation coming (unknown time) kismet.

'''Source code''': [https://github.com/CompleteNoobs/v4call https://github.com/CompleteNoobs/v4call]

'''End result''': A working v4call server at <code>https://call.yourdomain.com</code> that you can log into with a Hive account.

== Contents ==

* [[#What_You_Need|1 What You Need]]
* [[#Step_1:_Create_Your_Vultr_VPS|2 Step 1: Create Your Vultr VPS]]
* [[#Step_2:_Point_Your_Domain_at_the_VPS|3 Step 2: Point Your Domain at the VPS]]
* [[#Step_3:_Log_into_Your_VPS|4 Step 3: Log into Your VPS]]
* [[#Step_4:_Update_the_Server|5 Step 4: Update the Server]]
* [[#Step_5:_Install_Docker|6 Step 5: Install Docker]]
* [[#Step_6:_Install_Git|7 Step 6: Install Git]]
* [[#Step_7:_Fork_and_Clone_the_Code|8 Step 7: Fork and Clone the Code]]
* [[#Step_8:_Configure_Your_Server_(.env_file)|9 Step 8: Configure Your Server (.env file)]]
* [[#Step_9:_Configure_Nginx_—_HTTP_Only_First|10 Step 9: Configure Nginx — HTTP Only First]]
* [[#Step_10:_Create_Data_Directories_and_Fix_Permissions|11 Step 10: Create Data Directories and Fix Permissions]]
* [[#Step_11:_Build_and_Start_the_Server|12 Step 11: Build and Start the Server]]
* [[#Step_12:_Get_Your_SSL_Certificate|13 Step 12: Get Your SSL Certificate]]
* [[#Step_13:_Enable_HTTPS_in_Nginx|14 Step 13: Enable HTTPS in Nginx]]
* [[#Step_14:_Set_Up_SSL_Auto-Renewal|15 Step 14: Set Up SSL Auto-Renewal]]
* [[#Step_15:_Test_Everything_is_Working|16 Step 15: Test Everything is Working]]
* [[#Step_16:_Set_Up_Your_Call_Rates_on_Hive|17 Step 16: Set Up Your Call Rates on Hive]]
* [[#Feature_Guide:_What_Your_Server_Can_Do|18 Feature Guide: What Your Server Can Do]]
* [[#Admin_Configuration_Reference|19 Admin Configuration Reference]]
* [[#Updating_Your_Server|20 Updating Your Server]]
* [[#Common_Problems_and_Fixes|21 Common Problems and Fixes]]
* [[#Quick_Reference|22 Quick Reference]]

== What You Need ==

Before starting, make sure you have the following:

* '''A Vultr account''' — sign up at [https://vultr.com vultr.com] - please use are [https://www.vultr.com/?ref=7704739 Vultr Referral link] to help us cover server costs.
* '''A domain name''' with DNS access — e.g. <code>call.yourdomain.com</code>
* '''Two Hive accounts''' — one for your server identity (receives platform fees), one for escrow (holds caller funds during calls). Create free accounts at [https://signup.hive.io signup.hive.io]
* '''Hive Keychain browser extension''' — for login and payments. Install from [https://hive-keychain.com hive-keychain.com]
* '''A GitHub account''' — free at [https://github.com github.com]. You will fork the v4call project.
* '''A terminal''' — Mac: Terminal app. Windows: PowerShell or PuTTY.

You do not need to know how to code. Every command can be copy-pasted exactly as shown.

== Step 1: Create Your Vultr VPS ==

# Log into [https://my.vultr.com my.vultr.com]
# Click '''Deploy New Server'''
# Choose '''Cloud Compute — Shared CPU'''
# Choose a location close to you
# Choose '''Ubuntu 24.04 LTS x64'''
# Choose the '''$6/month''' plan (1 CPU, 1GB RAM)
# Set Server Hostname to something like <code>v4call-server</code>
# Click '''Deploy Now'''

Wait ~60 seconds for it to start. Click the server to find:
* '''IP Address''' — looks like <code>123.456.789.012</code> — write it down
* '''Password''' — click the eye icon — write it down

== Step 2: Point Your Domain at the VPS ==

Log into your DNS provider and add an A record:

{| class="wikitable"
|-
! Field !! Value
|-
| Type || A
|-
| Name || <code>call</code> (or <code>@</code> for root domain)
|-
| Value || Your VPS IP address
|-
| TTL || 300
|}

DNS takes a few minutes to propagate. Check from your computer later:

nslookup call.yourdomain.com

Must show your VPS IP before Step 12. You can continue with all other steps while waiting.

== Step 3: Log into Your VPS ==

Open a terminal on your computer:

ssh root@YOUR_SERVER_IP

Type <code>yes</code> when asked about the fingerprint, then paste the password from Vultr (right-click to paste in most terminals).

When you see <code>root@v4call-server:~#</code> you are in.

== Step 4: Update the Server ==

apt update && apt upgrade -y

Wait for it to complete (1-2 minutes).

== Step 5: Install Docker ==

Install Docker using the official installer script:

curl -fsSL https://get.docker.com | sh

Verify:

docker --version

Should show <code>Docker version 26.x.x</code> or similar.

Install Docker Compose plugin:

apt install -y docker-compose-plugin

Verify:

docker compose version

Should show <code>Docker Compose version v2.x.x</code>.

== Step 6: Install Git ==

apt install -y git
git --version

== Step 7: Download and/or Fork and Clone the Code ==

=== Clone onto your VPS ===

cd /opt
git clone https://github.com/CompleteNoobs/v4call.git
cd v4call

==== Fork on GitHub - Optional ====

Forking gives you your own copy of the code that you can customise — change the name, branding, fees — without affecting the original project.

# Go to [https://github.com/CompleteNoobs/v4call https://github.com/CompleteNoobs/v4call]
# Click the '''Fork''' button (top right of the page)
# Select your GitHub account as the destination
# Click '''Create fork'''

You now have your own copy at <code>https://github.com/YOURUSERNAME/v4call</code>

==== Clone onto your VPS ====

cd /opt
git clone https://github.com/YOURUSERNAME/v4call.git
cd v4call

List the files to confirm:

ls

You should see: <code>server.js public/ Dockerfile docker-compose.yml nginx/ package.json .env.example</code>

== Step 8: Configure Your Server (.env file) ==

All settings live in a single <code>.env</code> file. Copy the template:

cp .env.example .env
nano .env

Fill in your values:

<pre>
# ── Server Identity ──────────────────────────────────────
SERVER_NAME=yourcallapp
SERVER_DOMAIN=call.yourdomain.com
SERVER_HIVE_ACCOUNT=yourhiveaccount
ESCROW_ACCOUNT=yourescrowaccount
V4CALL_ESCROW_KEY=5Kxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# Secret key to access /admin/ledger and /admin/balance endpoints.
# Choose a long random string — treat it like a password.
# Example: openssl rand -hex 32
ADMIN_KEY=make-up-a-long-random-string-at-least-20-characters

# ── Hive Blockchain ──────────────────────────────────────
CHAIN=hive
HIVE_API=

# ── Platform Fee ─────────────────────────────────────────
# Percentage your server takes from each paid call/DM (10 = 10%)
# This is the MINIMUM fee — users whose rates post sets a lower
# platform fee will be rejected. Users who set a higher fee
# get the best price (your server's rate, not their higher number).
DEFAULT_PLATFORM_FEE=10

# ── Network ──────────────────────────────────────────────
PORT=3000
BIND_HOST=127.0.0.1

# ── Chat Storage ─────────────────────────────────────────
# How many days to keep stored DMs before automatic cleanup
DM_RETENTION_DAYS=33
# How many days to keep stored room messages before cleanup
ROOM_RETENTION_DAYS=33
# How many recent DMs per conversation to show on login (0 = off)
DM_PREVIEW_COUNT=1

# ── Call Behaviour (advanced — defaults are fine) ────────
# CALL_COOLDOWN_MS=30000
# MAX_CALL_DURATION_MIN=120
# PAYMENT_VERIFY_RETRIES=3
# PAYMENT_VERIFY_DELAY_MS=5000
</pre>

Key points:

* <code>V4CALL_ESCROW_KEY</code> — must be the '''active''' private key for your escrow account. Find it in your Hive wallet → Keys & Permissions → Active. Starts with <code>5K</code>. '''Never share this.'''
* <code>ADMIN_KEY</code> — invent a secret password for accessing admin tools
* <code>HIVE_API</code> — leave blank to use all built-in Hive nodes automatically
* <code>DEFAULT_PLATFORM_FEE</code> — your server's minimum platform fee percentage. See [[#Platform_Fee_System|Platform Fee System]] below for how this works.
* <code>DM_RETENTION_DAYS</code> / <code>ROOM_RETENTION_DAYS</code> — how long chat messages are kept in the database. A cleanup job runs every hour and deletes anything older. Set to <code>0</code> to keep messages indefinitely (not recommended).
* <code>DM_PREVIEW_COUNT</code> — when a user logs in, this many recent DMs per conversation are loaded into the lobby chat so they can see previews. Set to <code>0</code> to disable previews (users still get an unread count alert).

Save: '''Ctrl+X''' → '''Y''' → '''Enter'''

== Step 9: Configure Nginx — HTTP Only First ==

'''This step is critical.''' A very common mistake is putting the HTTPS/SSL config in Nginx before getting the certificate. Nginx tries to load the certificate at startup — if the file doesn't exist yet, Nginx crashes in a restart loop. Certbot then cannot serve the challenge because Nginx is down. Result: no certificate, stuck in a loop.

The fix: always start with HTTP only, get the certificate, then add HTTPS.

Edit the Nginx config:

nano /opt/v4call/nginx/v4call.conf

Delete everything and replace with this HTTP-only config:

<pre>
server {
listen 80;
server_name call.yourdomain.com www.call.yourdomain.com;

# Certbot challenge path — do not remove this block
location /.well-known/acme-challenge/ {
root /var/www/certbot;
}

# Proxy all other requests to the v4call app
location / {
proxy_pass http://app:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_read_timeout 86400;
}
}
</pre>

Replace <code>call.yourdomain.com</code> with your actual domain in both places.

Save: '''Ctrl+X''' → '''Y''' → '''Enter'''

== Step 10: Create Data Directories and Fix Permissions ==

Create the folders Docker uses for persistent data:

mkdir -p /opt/v4call/data/logs \
mkdir -p /opt/v4call/data/certbot/conf \
mkdir -p /opt/v4call/data/certbot/www/.well-known/acme-challenge \
mkdir -p /opt/v4call/data/certbot/logs

'''Fix permissions — do not skip this.'''

The v4call app runs inside Docker as user <code>node</code> (UID 1000). On the host, these directories are created by root, so the container cannot write to them. This causes a <code>SQLITE_CANTOPEN</code> error that crashes the app.

Fix the logs directory for the app:

chown -R 1000:1000 /opt/v4call/data/logs

Certbot runs as root so its directories stay root-owned:

chown -R root:root /opt/v4call/data/certbot
chmod -R 755 /opt/v4call/data/certbot

'''Note:''' The app creates two separate SQLite databases in the logs directory:
* <code>v4call-ledger.db</code> — payment records (calls, ring fees, payouts). Only the server writes to this.
* <code>v4call-chat.db</code> — stored DMs and room messages. Separate from the ledger for security — if a bug in chat storage were exploited, the payment ledger remains untouched.

== Step 11: Build and Start the Server ==

cd /opt/v4call
docker compose up -d --build

The first build downloads dependencies and takes 2-4 minutes. Check the status:

docker compose ps

You should see:

<pre>
NAME STATUS
v4call-app Up (healthy)
v4call-nginx Up
</pre>

Check the app started correctly:

docker compose logs app

Look for:

<pre>
[ledger] SQLite ready: /app/logs/v4call-ledger.db
[chat] SQLite ready: /app/logs/v4call-chat.db
v4call server running on 0.0.0.0:3000
[config] Server: yourcallapp (call.yourdomain.com)
[config] DM retention: 33 days | Room retention: 33 days | DM preview: 1
✓ Escrow key verified — matches @yourescrowaccount active key
✓ Escrow account @yourescrowaccount balance: 0.000 HBD
</pre>

If you see <code>SqliteError: unable to open database file</code> — run the chown command from Step 10 again then <code>docker compose restart app</code>.

Test HTTP is working:

curl http://call.yourdomain.com/debug-state

Should return: <code>{"lobbyUsers":[],"rooms":[]}</code>

If you can see the site in a browser over HTTP at this point — everything is working and ready for the certificate.

== Step 12: Get Your SSL Certificate ==

'''Before running certbot''', verify DNS and the challenge path are both working:

# Check DNS points to this server
nslookup call.yourdomain.com

# Test the challenge path
echo "test" > /opt/v4call/data/certbot/www/.well-known/acme-challenge/testfile
curl http://call.yourdomain.com/.well-known/acme-challenge/testfile

The curl command must return <code>test</code>. If it does not, Nginx is not running — check <code>docker compose ps</code> and <code>docker compose logs nginx</code>.

When both work, get the certificate. The <code>--entrypoint certbot</code> flag is required — without it, Docker runs the container's default renewal loop instead of the certonly command:

docker compose run --rm \
--entrypoint certbot \
certbot certonly \
--webroot \
-w /var/www/certbot \
-d call.yourdomain.com \
--email your@email.com \
--agree-tos \
--no-eff-email

Replace <code>call.yourdomain.com</code> with your domain and <code>your@email.com</code> with your email.

Success looks like:

<pre>
Requesting a certificate for call.yourdomain.com

Successfully received certificate.
Certificate is saved at: /etc/letsencrypt/live/call.yourdomain.com/fullchain.pem
Key is saved at: /etc/letsencrypt/live/call.yourdomain.com/privkey.pem
This certificate expires on 2026-07-09.
</pre>

Verify the files exist on the host:

ls /opt/v4call/data/certbot/conf/live/call.yourdomain.com/

Should show: <code>cert.pem chain.pem fullchain.pem privkey.pem README</code>

== Step 13: Enable HTTPS in Nginx ==

Now the certificate exists, update Nginx to serve HTTPS.

nano /opt/v4call/nginx/v4call.conf

Replace everything with the full HTTPS config:

<pre>
# HTTP — only used for certbot challenge and redirect to HTTPS
server {
listen 80;
server_name v4call.com v4call.com;

location /.well-known/acme-challenge/ {
root /var/www/certbot;
}

location / {
return 301 https://$host$request_uri;
}
}

# HTTPS — auth lives here
server {
listen 443 ssl;
server_name v4call.com v4call.com;
# CHANGE PATH: for ssl certifcates change v4call.com to your path: which you can find at "ls data/certbot/conf/live/"
ssl_certificate /etc/letsencrypt/live/v4call.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/v4call.com/privkey.pem;

ssl_protocols TLSv1.2 TLSv1.3;
ssl_prefer_server_ciphers off;

add_header Strict-Transport-Security "max-age=63072000" always;
add_header X-Frame-Options DENY;
add_header X-Content-Type-Options nosniff;

# When user cancels the login prompt, send them here
error_page 401 /info.html;

# info.html is served directly by Nginx — no auth, no proxy
location = /info.html {
root /usr/share/nginx/html;
auth_basic off;
}

# WebSocket — requires auth
location /socket.io/ {
# uncomment to require username and password to enter site - useful for testing
# auth_basic "v4call — Private Testing";
# auth_basic_user_file /etc/nginx/.htpasswd;

proxy_pass http://app:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_cache_bypass $http_upgrade;
proxy_read_timeout 86400;
}

# Everything else — requires auth, proxied to app
location / {
# uncomment to require username and password to enter site - useful for testing
# auth_basic "v4call — Private Testing";
# auth_basic_user_file /etc/nginx/.htpasswd;

proxy_pass http://app:3000;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_read_timeout 300;
proxy_send_timeout 300;
}
# This will log correct and incorrect attempts logging in, if .htpasswd used
error_log /var/log/nginx/error.log warn;
access_log /var/log/nginx/access.log;
}
</pre>

* REPLACE <code>call.yourdomain.com</code> with your domain throughout (it appears 5 times).
* CHANGE PATH: for ssl certifcates change v4call.com to your path: which you can find at <code>ls data/certbot/conf/live/</code> if not sure.
<pre>
ssl_certificate /etc/letsencrypt/live/v4call.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/v4call.com/privkey.pem;
</pre>

Save and restart Nginx:

docker compose restart nginx

Check the logs — you should see '''no''' <code>[emerg]</code> errors:

docker compose logs nginx

The last lines should show:

<pre>
nginx/1.x.x ...
start worker processes
</pre>

* If you see an error such as:
<pre>[emerg] 1#1: cannot load certificate "/etc/letsencrypt/live/call.yourdomain.com/fullchain.pem": BIO_new_file() failed (SSL: error:80000002:system library::No such file or directory:calling fopen(/etc/letsencrypt/live/call.yourdomain.com/fullchain.pem, r) error:10000080:BIO routines::no such file)</pre>

* Make sure you edited <code>nginx/v4call.conf</code> correctly.
* To find the path for your SSL certs look in path <code>data/certbot/conf/live/</code>
* There are 4 lines to check in <code>nginx/v4call.conf</code>:
** Line 4: <code>server_name call.yourdomain.com www.call.yourdomain.com;</code>
** Line 18: <code>server_name call.yourdomain.com www.call.yourdomain.com;</code>
** Line 20: <code>ssl_certificate /etc/letsencrypt/live/call.yourdomain.com/fullchain.pem;</code>
** Line 21: <code>ssl_certificate_key /etc/letsencrypt/live/call.yourdomain.com/privkey.pem;</code>
* When done restart nginx with: <code>docker compose restart nginx</code>

== Step 14: Set Up SSL Auto-Renewal ==

Let's Encrypt certificates expire after 90 days. A cron job renews them automatically.

crontab -e

Add this line at the bottom:

0 3 * * * cd /opt/v4call && docker compose run --rm --entrypoint certbot certbot renew --quiet && docker compose exec nginx nginx -s reload

Save and exit. This runs at 3am every day, renews if the cert is close to expiry, and reloads Nginx to pick up the new certificate.

== Step 15: Test Everything is Working ==

Test HTTPS:

curl https://call.yourdomain.com/debug-state

Should return: <code>{"lobbyUsers":[],"rooms":[]}</code>

Test admin access:

curl "https://call.yourdomain.com/admin/balance?key=YOUR_ADMIN_KEY"

Should return your escrow account balance.

Open your browser and go to <code>https://call.yourdomain.com</code>

You should see the v4call login page with:
* A padlock icon in the browser address bar
* A green '''⚡ Sign in with Keychain''' button (if Hive Keychain is installed)
* A manual posting key login option below it
* A '''📖 New here? Learn the v4call basics →''' link at the bottom

Log in with Hive Keychain or a posting key to confirm the login flow works. 🎉

== Step 16: Set Up Your Call Rates on Hive ==

For callers to be charged when they ring you, publish your rates on the Hive blockchain:

# Make sure Hive Keychain is installed in your browser
# Go to <code>https://call.yourdomain.com/rate-editor.html</code>
# Enter your Hive username
# Set your rates — ring fee, connect fee, duration rate per hour, minimum credit deposit
# Set <code>PLATFORM-FEE</code> to at least your server's <code>DEFAULT_PLATFORM_FEE</code> percentage (e.g. <code>10</code> for 10%). If you set it lower, paid contacts to your account will be rejected on this server.
# Optionally add custom token sections (e.g. <code>[TOKEN:CNOOBS]</code>) to offer discounted rates for callers who hold your token
# Click '''Generate''' to preview the rates block
# Click '''Post to Hive''' — Keychain will ask you to approve the post

This creates a post titled <code>v4call-rates</code> on your Hive blog. Your server reads this post automatically.

To verify your server read the rates correctly:

https://call.yourdomain.com/debug-rates/yourusername

To test with a specific caller (checks their token balances too):

https://call.yourdomain.com/debug-rates/yourusername?caller=theirusername&type=voice

You should see your rates as JSON, including which currency and rates apply for that caller.

== Feature Guide: What Your Server Can Do ==

This section explains all the features available in v4call and how they work. No code changes needed — everything described here is built in and ready to use.

=== Login Options ===

v4call supports two ways to sign in:

* '''Hive Keychain''' (recommended) — click the green '''⚡ Sign in with Keychain''' button. Keychain signs a challenge to prove your identity. No key paste needed. After login, a 🔑 panel appears in the lobby where you can optionally enter your posting key to unlock encrypted messaging (Keychain cannot expose private keys, so encryption needs the key entered once per session).
* '''Manual posting key''' — paste your Hive posting private key (starts with <code>5J</code>) directly. The key stays in browser session memory only — never sent to the server.

Both methods verify your identity against the Hive blockchain.

=== Voice and Video Calls ===

Each online user in the lobby shows three action buttons:

* '''📞 Green phone icon''' — start a '''voice-only''' call (audio, no camera)
* '''🎥 Blue camera icon''' — start a '''video''' call (audio + camera)
* '''💬 Purple chat bubble icon''' — open the '''DM panel''' to send a direct message

Voice calls request microphone only — no camera permission prompt. Video calls request both. The caller and callee can have different call types — the type is set by whoever initiates the call.

Separate rates can be set for voice and video calls in the rates post (voice is typically cheaper).

=== Direct Messages (DMs) ===

Click the purple 💬 button next to any online user to open the DM panel. DMs are end-to-end encrypted using Hive posting keys — the server stores only ciphertext it cannot read.

'''Chat storage:''' DMs are stored on the server in an encrypted database (<code>v4call-chat.db</code>) for up to <code>DM_RETENTION_DAYS</code> (default: 33 days). Both sender and recipient get their own encrypted copy stored, so both can retrieve their history later.

'''Unread alerts:''' When you log in, if you have unread DMs, a popup appears showing how many messages from how many users. Click a username in the popup to open their DM history.

'''DM previews:''' The last <code>DM_PREVIEW_COUNT</code> messages per conversation are loaded into the lobby chat on login, so you can see recent activity at a glance. Set to <code>0</code> in <code>.env</code> to disable.

'''Full history:''' Click the DM button for any user to load the complete conversation history, shown between "— DM history —" dividers.

=== Rooms ===

Users can create private rooms by selecting users in the lobby (toggle switch) and clicking '''Create & Invite'''. Rooms support encrypted messaging, video, and voice.

'''Room history:''' When a new user joins a room, they see past messages — broadcasts in full, encrypted messages only if they were addressed to them. A "— earlier messages —" divider separates history from live messages.

'''Ephemeral rooms:''' A warning banner at the top of every room says: "⚠ Room is ephemeral — if all users leave, the room and its history are deleted. New members can only read messages encrypted to their key." When the last person leaves a room, all stored messages for that room are deleted from the database.

=== Custom Token Payments (Hive-Engine) ===

v4call supports payment in any Hive-Engine token, not just HBD. This is configured per-user in their rates post using <code>[TOKEN:SYMBOL]</code> sections.

'''How it works:'''
# A user (e.g. @cnoobz) creates a custom token on Hive-Engine (e.g. CNOOBS)
# In their rates post, they add a <code>[TOKEN:CNOOBS]</code> section with lower rates than their default HBD rates
# When a caller who holds CNOOBS contacts @cnoobz, the server detects the token balance and offers the token rates
# If the caller holds multiple qualifying tokens, '''all options are shown''' in a currency picker — the caller chooses which to pay with
# The payment goes through Hive Keychain as a <code>custom_json</code> Hive-Engine transfer

'''For the escrow account:''' Your escrow account needs to hold some of each custom token that users on your server accept. Token payouts (to the callee) and refunds (to the caller) are sent from the escrow account's token balance, just like HBD.

'''Payment picker:''' When multiple payment options exist (e.g. CNOOBS at 1 per message, HBD at 100000 per message), the payment modal shows clickable currency buttons so the caller can see all rates and choose the best option.

=== Platform Fee System ===

The platform fee is how your server earns revenue from paid calls and DMs.

'''How it works:'''
* Your server's <code>DEFAULT_PLATFORM_FEE</code> in <code>.env</code> is the '''minimum''' percentage your server accepts (e.g. <code>10</code> = 10%)
* Each user sets <code>PLATFORM-FEE</code> in their Hive rates post — this is the maximum fee they are willing to pay to a server
* If the user's posted fee is '''lower''' than your server's minimum → '''rejected'''. The caller sees a message explaining the mismatch, and the callee is told to raise their fee.
* If the user's posted fee '''meets or exceeds''' your server's minimum → '''accepted''', and '''the server charges its own rate''' (the minimum), not the user's higher number. The callee gets the best price.
* If the user has '''no <code>PLATFORM-FEE</code> line''' in their rates post → the server's default is used automatically. No mismatch.
* '''Free contacts''' (no payment involved) are never affected by fee enforcement.

'''Why this matters for federation:''' Different servers can set different platform fees. Users can shop around — pick a server with a fee they find agreeable. This creates a free market for server operators.

'''Example:'''
* Your server: <code>DEFAULT_PLATFORM_FEE=3</code> (3%)
* @alice posts: <code>PLATFORM-FEE: 5%</code> → accepted, server charges 3% (best price for alice)
* @bob posts: <code>PLATFORM-FEE: 1%</code> → rejected, bob needs to raise to at least 3%
* @charlie has no fee line → defaults to 3%, automatically accepted

== Admin Configuration Reference ==

All settings are in the <code>.env</code> file. After changing any value, rebuild:

docker compose down && docker compose build --no-cache && docker compose up -d

{| class="wikitable"
|-
! Variable !! Default !! Description
|-
| <code>SERVER_NAME</code> || <code>v4call</code> || Display name for your server
|-
| <code>SERVER_DOMAIN</code> || <code>v4call.com</code> || Your server's domain
|-
| <code>SERVER_HIVE_ACCOUNT</code> || <code>v4call</code> || Hive account that receives platform fees
|-
| <code>ESCROW_ACCOUNT</code> || <code>v4call-escrow</code> || Hive account that holds funds during calls
|-
| <code>V4CALL_ESCROW_KEY</code> || ''(none)'' || Active private key for the escrow account. '''Required.'''
|-
| <code>ADMIN_KEY</code> || ''(none)'' || Password for admin endpoints (<code>/admin/balance</code>, <code>/admin/ledger</code>)
|-
| <code>DEFAULT_PLATFORM_FEE</code> || <code>10</code> || Server's minimum platform fee percentage
|-
| <code>DM_RETENTION_DAYS</code> || <code>33</code> || Days to keep stored DMs before cleanup
|-
| <code>ROOM_RETENTION_DAYS</code> || <code>33</code> || Days to keep stored room messages before cleanup
|-
| <code>DM_PREVIEW_COUNT</code> || <code>1</code> || Recent DMs per conversation shown on login (0 = off)
|-
| <code>HIVE_API</code> || ''(blank)'' || Override primary Hive API node. Blank = auto-select from built-in list
|-
| <code>MAX_CALL_DURATION_MIN</code> || <code>120</code> || Maximum call length in minutes before auto-disconnect
|-
| <code>CALL_COOLDOWN_MS</code> || <code>30000</code> || Milliseconds between call attempts to same user
|-
| <code>PAYMENT_VERIFY_RETRIES</code> || <code>3</code> || Number of attempts to verify a blockchain payment
|-
| <code>PAYMENT_VERIFY_DELAY_MS</code> || <code>5000</code> || Delay between verification retry attempts
|}

=== Debug Endpoints ===

These are useful for testing without making actual calls:

* <code>/debug-state</code> — shows current lobby users and active rooms (no auth required)
* <code>/debug-rates/USERNAME</code> — shows parsed rates for a user
* <code>/debug-rates/USERNAME?caller=CALLER&type=voice</code> — shows what rates a specific caller would receive (checks token balances too)
* <code>/admin/balance?key=YOUR_ADMIN_KEY</code> — shows escrow account HBD balance
* <code>/admin/ledger?key=YOUR_ADMIN_KEY</code> — shows recent payment records

== Updating Your Server ==

'''Important:''' Always use <code>docker compose down</code> before rebuilding. Without this step, Docker may reuse the old container even after a rebuild, and your changes will not take effect.

cd /opt/v4call
docker compose down
docker compose build --no-cache
docker compose up -d

Your data, SQLite databases and <code>.env</code> config are preserved — they live in <code>data/logs/</code> which is a mounted volume.

To pull updates from GitHub and deploy:

cd /opt/v4call
git pull
docker compose down
docker compose build --no-cache
docker compose up -d

To push your own customisations to GitHub:

# On your local computer after making changes:
git add .
git commit -m "describe what you changed"
git push

# On the VPS:
cd /opt/v4call
git pull
docker compose down
docker compose build --no-cache
docker compose up -d

== Common Problems and Fixes ==

=== Changes not showing after rebuild ===

If you edited <code>server.js</code> or <code>index.html</code> but changes are not visible, you probably forgot to bring Docker down first. <code>docker compose restart</code> and even <code>docker compose up -d --build</code> can reuse old containers.

'''Fix:'''

docker compose down
docker compose build --no-cache
docker compose up -d

=== SqliteError: unable to open database file ===

The app container runs as UID 1000 but the logs directory was created by root. Fix:

chown -R 1000:1000 /opt/v4call/data/logs
docker compose restart app

=== Certbot says "No renewals were attempted" ===

The certbot container's default behaviour is a renewal loop. Your <code>certonly</code> command is being ignored. Always use <code>--entrypoint certbot</code> to override it:

docker compose run --rm --entrypoint certbot certbot certonly ...

Without <code>--entrypoint certbot</code> the container runs its renewal script instead of your command.

=== Nginx crashes with "cannot load certificate: No such file" ===

You added the HTTPS server block before getting the certificate. Nginx reads all server blocks at startup — if the cert file doesn't exist, the entire process fails.

Fix: revert nginx config to HTTP-only (Step 9), restart Nginx, get the certificate (Step 12), then re-add HTTPS (Step 13).

=== Webroot challenge test returns nothing ===

Nginx is not running. Check:

docker compose ps
docker compose logs nginx

If Nginx is restarting — it has the HTTPS config with a missing cert file. Use the HTTP-only config.

=== "Escrow key does NOT match" warning on startup ===

The key in <code>.env</code> is the wrong type. You need the '''active''' private key, not the posting or owner key. Find it in your Hive wallet → Keys & Permissions → Active. It starts with <code>5K</code>.

=== Site unreachable on port 443 ===

Check that the certificate was issued:

ls /opt/v4call/data/certbot/conf/live/

Should show a folder with your domain name. If empty — go back to Step 12.

=== npm ci error during Docker build ===

The <code>npm ci</code> command requires a <code>package-lock.json</code> file. The project uses <code>npm install</code> instead. If you see this error, check your <code>Dockerfile</code> — it should say <code>npm install</code> not <code>npm ci</code>.

=== Custom token payments not working ===

If token rates are detected but payments fail:
* Check the escrow account holds the token — send some tokens to your escrow account on Hive-Engine
* Check the token symbol matches exactly (case-sensitive) between the rates post and Hive-Engine
* Check the server logs: <code>docker compose logs app | grep -i "token\|cnoobs\|escrow-token"</code>
* The Hive-Engine API endpoint must be <code>https://api.hive-engine.com/rpc/contracts</code> — this is built into the code

=== [encrypted — unlock with 🔑 key panel to read] ===

You logged in with Hive Keychain. Keychain does not expose private keys, so encrypted messages cannot be decrypted without your posting key. Enter your posting key in the 🔑 panel at the bottom of the online users list. The key stays in browser session memory only — it is needed once per session.

== Quick Reference ==

{| class="wikitable"
|-
! Command !! What it does
|-
| <code>docker compose ps</code> || Show status of all containers
|-
| <code>docker compose logs app</code> || Show app logs
|-
| <code>docker compose logs nginx</code> || Show Nginx logs
|-
| <code>docker compose logs -f app</code> || Watch live logs (Ctrl+C to stop)
|-
| <code>docker compose down</code> || Stop everything ('''always do this before rebuilding''')
|-
| <code>docker compose build --no-cache</code> || Rebuild without using cached layers
|-
| <code>docker compose up -d</code> || Start everything in background
|-
| <code>docker compose down && docker compose build --no-cache && docker compose up -d</code> || Full rebuild cycle (use after any code change)
|-
| <code>docker compose restart nginx</code> || Restart Nginx after config-only changes (no rebuild needed)
|-
| <code>chown -R 1000:1000 /opt/v4call/data/logs</code> || Fix SQLite write permissions
|-
| <code>docker compose run --rm --entrypoint certbot certbot certificates</code> || List SSL certificates
|-
| <code>curl http://yourdomain.com/.well-known/acme-challenge/testfile</code> || Test certbot webroot works
|-
| <code>docker compose logs app | grep -i "token\|escrow"</code> || Check token payment logs
|}

== Optional: Password Protect Your Server During Testing ==

<div class="toccolours mw-collapsible mw-collapsed">
<strong>Optional: Password Protect Your Server During Testing (HTTP Basic Auth)</strong>
<div class="mw-collapsible-content">

During development and testing you may want to restrict access so only people you invite can use your server. This uses Nginx HTTP Basic Auth — a simple username and password prompt that appears before the v4call login screen.

When a visitor cancels the login prompt they are shown a public <code>info.html</code> page where they can read about the project and request access.

*<b> Step 1 — Install the htpasswd tool</b>

<code>apt install -y apache2-utils</code>

*<b> Step 2 — Create the password file and add your first user </b>

<code>htpasswd -c /opt/v4call/nginx/.htpasswd yourusername</code>

You will be prompted to enter and confirm a password. The <code>-c</code> flag creates the file. Do not use <code>-c</code> again or it will overwrite the file and delete existing users.

To add more users later:

<code>htpasswd /opt/v4call/nginx/.htpasswd anotherusername</code>

To remove a user:

<code>htpasswd -D /opt/v4call/nginx/.htpasswd username</code>

*<b> Step 3 — Create the public info page </b>

<code>nano /opt/v4call/public/info.html</code>

Paste your HTML content — a page explaining the project and how to request access. This page is served publicly without a password so visitors who cancel the login prompt can still read it.

*<b> Step 4 — Mount the files into the Nginx container </b>

Edit <code>docker-compose.yml</code> and add two lines to the nginx volumes section:

<pre>
nginx:
volumes:
- ./nginx/v4call.conf:/etc/nginx/conf.d/default.conf:ro
- ./nginx/.htpasswd:/etc/nginx/.htpasswd:ro # add this
- ./public/info.html:/usr/share/nginx/html/info.html:ro # add this
- ./data/certbot/conf:/etc/letsencrypt:ro
- ./data/certbot/www:/var/www/certbot:ro
</pre>

*<b> Step 5 — Update your Nginx config </b>

Add auth to the '''HTTPS server block''' (not the HTTP block — users are redirected to HTTPS so auth must live there). Add these lines to both the <code>/socket.io/</code> and <code>/</code> location blocks, and add the <code>error_page</code> and <code>info.html</code> location blocks:

<pre>
server {
listen 443 ssl;
server_name call.yourdomain.com www.call.yourdomain.com;

# ... ssl_certificate lines stay the same ...

# Send cancelled logins to the public info page
error_page 401 /info.html;

# info.html is served by Nginx directly — no auth, no proxy
location = /info.html {
root /usr/share/nginx/html;
auth_basic off;
}

# WebSocket — requires auth
location /socket.io/ {
auth_basic "v4call — Private Testing";
auth_basic_user_file /etc/nginx/.htpasswd;
proxy_pass http://app:3000;
# ... rest of proxy headers stay the same ...
}

# All other requests — requires auth
location / {
auth_basic "v4call — Private Testing";
auth_basic_user_file /etc/nginx/.htpasswd;
proxy_pass http://app:3000;
# ... rest of proxy headers stay the same ...
}
}
</pre>
* Note: if you want to log successful and unsuccessful login attempts, add:
<pre>
error_log /var/log/nginx/error.log warn;
access_log /var/log/nginx/access.log;
</pre>

*<b> Step 6 — Recreate the Nginx container to pick up the new volume mounts </b>

'''Important''': <code>docker compose restart nginx</code> is not enough — it reuses the old container and ignores new volume mounts. You must recreate it:

<code>docker compose down && docker compose up -d</code>

After this, verify the files are mounted inside the container:

<code>docker compose exec nginx ls /usr/share/nginx/html/</code>

You should see <code>info.html</code> listed alongside <code>50x.html</code> and <code>index.html</code>.

*<b> Step 7 — Test it works </b>

<code>curl -o /dev/null -s -w "%{http_code}" https://call.yourdomain.com/</code>

Should return <code>401</code> (login required).

<code>curl -o /dev/null -s -w "%{http_code}" https://call.yourdomain.com/info.html</code>

Should return <code>200</code> (public, no auth needed).

<code>curl -u youruser:yourpassword -o /dev/null -s -w "%{http_code}" https://call.yourdomain.com/</code>

Should return <code>200</code> (correct credentials accepted).

*<b> Managing users without restarting </b>

After adding or removing users from the <code>.htpasswd</code> file, reload Nginx config without downtime:

<code>docker compose exec nginx nginx -s reload</code>

No restart needed — Nginx re-reads the <code>.htpasswd</code> file on every request anyway.

*<b> Keep .htpasswd out of GitHub </b>

The password file should never be committed to your repository. Add it to <code>.gitignore</code>:

<code>echo "nginx/.htpasswd" >> /opt/v4call/.gitignore</code>

*<b> Removing auth when you go public </b>

When you are ready to open your server to everyone, simply remove the <code>auth_basic</code> lines from <code>nginx/v4call.conf</code> and reload:

<code>docker compose exec nginx nginx -s reload</code>

No other changes needed.

</div>
</div>

<div class="toccolours mw-collapsible mw-collapsed">
'''How to check if anyone tried to log in (failed attempts) or successfully logged in with .htpasswd on Nginx in Docker'''

<div class="mw-collapsible-content">

'''Important Tip:''' Always run these commands in the same folder where your <code>docker-compose.yml</code> file is located. If you are in the wrong directory the commands will not find your container and nothing will show up.

* ''''' Basic Commands '''''

; '''See everything live (good while testing)'''
: <code>docker compose logs -f nginx</code><br>
: <code>-f</code> means "follow/live" – new log lines appear automatically. Remove <code>-f</code> if you only want to read the current logs once and stop.

; '''Best command to watch failed login attempts (people guessing passwords)'''
: <code>docker compose logs -f nginx | grep -E "mismatch|not found|401"</code>

; '''See who successfully logged in'''
: <code>docker compose logs nginx | grep "remote_user"</code>

; '''Combined view – most useful for daily checking (failed + successful)'''
: <code>docker compose logs -f --tail=100 nginx | grep -E "(mismatch|not found|remote_user|401)"</code>

* ''''' What the Logs Look Like '''''

'''Failed attempt (wrong password):'''
<pre>2026/04/17 01:23:45 [error] ... user "admin": password mismatch, client: 185.123.45.67, ...</pre>

'''Failed attempt (wrong username):'''
<pre>2026/04/17 01:24:12 [error] ... user "hacker123" was not found in "/etc/nginx/.htpasswd", client: 45.67.89.10, ...</pre>

'''Successful login:'''
<pre>... "GET /protected/ HTTP/1.1" 200 ... remote_user: "myuser" ...</pre>

* ''''' How to Customise These Commands '''''

* Change <code>nginx</code> to the exact name of your service if it is different in docker-compose.yml.
* Remove <code>-f</code> to read the full log once without live following.
* Change <code>--tail=100</code> to <code>--tail=500</code> (or any number) to show more or fewer old lines.
* Add or remove words in the <code>grep</code> part to filter differently.
Examples:
* Only failed attempts: <code>grep -E "mismatch|not found"</code>
* Only 401 errors: <code>grep " 401 "</code>
* Everything auth related: <code>grep -E "(auth|password|mismatch|not found|remote_user)"</code>

* '''''Quick Copy-Paste Commands '''''

# Watch failed guesses live
docker compose logs -f nginx | grep -E "mismatch|not found|401"

# Check successful logins
docker compose logs nginx | grep "remote_user"

# Combined quick check (recommended)
docker compose logs -f --tail=100 nginx | grep -E "(mismatch|not found|remote_user|401)"

</div>
</div>

[[Category:Docker]]
[[Category:Ubuntu]]
[[Category:Hive]]
[[Category:v4call]]
[[Category:WebRTC]]

Main Page

2026-04-19T14:16:23Z

AwesomO: /* Licenses */

=In Concept development Mode - a wiki you can download=
= CompleteNoobs: A Downloadable Wiki for Reproducible Computer Tutorials =

'''CompleteNoobs''' is a open-source wiki offering free, reproducible computer science tutorials.

* [[Ubuntu2404_Install_Docker_and_Docker_Compose| Download the wiki as a '''Docker image''' to run locally on your computer or fork it to contribute and share knowledge.]]

== About CompleteNoobs ==

Our mission is to provide accessible, libre-licensed resources for hobbyists, sysadmins, students, teachers, and computer science enthusiasts. All content is available under a '''Creative Commons BY-NC-SA''' license, ensuring the freedoms to:
* Read
* Edit/Modify
* Copy
* Share freely

Download the wiki as an XML file at [https://xml.completenoobs.com xml.completenoobs.com] or access data-heavy content (images, videos, audio) via '''IPFS''' hashes.

== Get Started ==

* '''Download the Wiki''': Run CompleteNoobs locally using our [[Local_CompleteNoobs_Wiki|Manually install guides or Docker image]].
* '''Host Your Own''': Set up your own MediaWiki instance with our guide: [[Host_Your_Own_Mediawiki_Online|Host Your Own MediaWiki Online]].

== CompleteNoobs Blockchain Project ==

As Noobs we want to learn more about bitcoin, without losing any real bitcoin

First we are learning how to fork bitcoin version 0.14.3, best way to learn is by tinkering with it.
* [[N33Bcoin| n33b.com]]

== Essential Links ==

* [[Main_Index|Main Index Page]]
* [[Special:AllPages|All Pages]]
* [[Wiki_Basic_Syntax|Wiki Basic Syntax]]
* [[COMPLETENOOBS_FUNDING|Support Us]]

== Licenses ==
[[LICENCE_HEADERS]]
All content is libre-licensed for free copying, modification, and distribution. Add a license header to your contributions using:
<pre>{{:LICENCE_HEADER_CC0}}</pre>
{{:LICENCE_HEADER_CC0}}

== Disclaimer ==

<div class="toccolours mw-collapsible mw-collapsed">
'''''DISCLAIMER:'''''
<div class="mw-collapsible-content">
Content on CompleteNoobs is for informational and educational purposes only. We make no warranties about accuracy or reliability. Use at your own risk. Links to external sites are not endorsements, and we are not responsible for their content or availability. The site may be temporarily unavailable due to technical issues beyond our control.
</div>
</div>

{{Special:ContributionScores/10/5}}
{{Special:PopularPages/10}}

Hive Blockchain - How to change Active and Posting keys on Hive

2026-04-19T13:57:14Z

AwesomO: Created page with "'''How to Change Your Active and Posting Keys on Hive (2026)''' To update your Active, Posting (or any) keys on Hive, you must perform a full **password reset**. This generates a new '''Master Password''' that automatically creates a fresh set of all keys (Owner, Active, Posting, Memo). =='''Critical Warnings'''== * If you lose the new Master Password or Owner Key, '''no one''' (not even Hive support) can recover your account. * '''Backup everything''' (especially the..."

'''How to Change Your Active and Posting Keys on Hive (2026)'''

To update your Active, Posting (or any) keys on Hive, you must perform a full **password reset**. This generates a new '''Master Password''' that automatically creates a fresh set of all keys (Owner, Active, Posting, Memo).

=='''Critical Warnings'''==
* If you lose the new Master Password or Owner Key, '''no one''' (not even Hive support) can recover your account.
* '''Backup everything''' (especially the new Master Password and all private keys) before clicking Update.
* You will need to manually add the new keys to Hive Keychain and other apps afterward.

=='''Method 1: Official Hive Wallet (wallet.hive.blog)'''==
# Go to [https://wallet.hive.blog wallet.hive.blog] (or directly to <code>https://wallet.hive.blog/@yourusername/permissions</code>).
# Log in using your current '''Owner Key''' or '''Master Password'''.
# Navigate to the '''Change Password''' section.
# Click '''"Click to Generate Password"'''.
# '''Save everything''': Copy the new Master Password and all displayed private/public keys. Store them securely offline.
# Re-enter the new Master Password in the confirmation field.
# Check all confirmation boxes.
# Click '''Update Password'''.

=='''Method 2: Using PeakD (often easier)'''==
# Log in to [https://peakd.com peakd.com] (usually via Hive Keychain).
# Go to your profile → '''Wallet''' → '''Keys & Permissions'''.
# Click the '''Change Password''' button.
# Authorize with your current '''Owner Key'''.
# Generate the new password, download/save all keys, then confirm the update.

=='''After Updating'''==
* Update Hive Keychain (remove old keys and import the new ones).
* Update any mobile apps (Ecency, Hive Wallet, etc.).
* Test logging in with the new keys before deleting old backups.

*'''Tip''': Always keep your Owner Key extremely safe — it is the only key that can reset everything.

==Expanding info box==

<div class="toccolours mw-collapsible mw-collapsed">
'''How to Change Your Active and Posting Keys on Hive (2026)'''

<div class="mw-collapsible-content">

To update your Active, Posting (or any) keys on Hive, you must perform a full **password reset**. This generates a new '''Master Password''' that automatically creates a fresh set of all keys (Owner, Active, Posting, Memo).

'''Critical Warnings'''
* If you lose the new Master Password or Owner Key, '''no one''' (not even Hive support) can recover your account.
* '''Backup everything''' (especially the new Master Password and all private keys) before clicking Update.
* You will need to manually add the new keys to Hive Keychain and other apps afterward.

'''Method 1: Official Hive Wallet (wallet.hive.blog)'''
# Go to [https://wallet.hive.blog wallet.hive.blog] (or directly to <code>https://wallet.hive.blog/@yourusername/permissions</code>).
# Log in using your current '''Owner Key''' or '''Master Password'''.
# Navigate to the '''Change Password''' section.
# Click '''"Click to Generate Password"'''.
# '''Save everything''': Copy the new Master Password and all displayed private/public keys. Store them securely offline.
# Re-enter the new Master Password in the confirmation field.
# Check all confirmation boxes.
# Click '''Update Password'''.

'''Method 2: Using PeakD (often easier)'''
# Log in to [https://peakd.com peakd.com] (usually via Hive Keychain).
# Go to your profile → '''Wallet''' → '''Keys & Permissions'''.
# Click the '''Change Password''' button.
# Authorize with your current '''Owner Key'''.
# Generate the new password, download/save all keys, then confirm the update.

'''After Updating'''
* Update Hive Keychain (remove old keys and import the new ones).
* Update any mobile apps (Ecency, Hive Wallet, etc.).
* Test logging in with the new keys before deleting old backups.

'''Tip''': Always keep your Owner Key extremely safe — it is the only key that can reset everything.

</div>
</div>

Hive Blockchain - buying/exchanging Hive Based Dollars $HBD

2026-04-19T12:48:22Z

AwesomO: Created page with "= Hive Blockchain Buying HBD = == Prerequisites == Before buying HBD, you must have a Hive account. It is recommended to use Hive Keychain for easy and secure access to your account. * Create a Hive account (see: ''Hive Blockchain Create Extra Accounts'') * Install Hive Keychain (browser extension) * Log in to your account using your keys == Buying HIVE from an Exchange == To obtain HBD, you will first need to buy HIVE from a cryptocurrency exchange. Example (UK): *..."

= Hive Blockchain Buying HBD =

== Prerequisites ==
Before buying HBD, you must have a Hive account.

It is recommended to use Hive Keychain for easy and secure access to your account.

* Create a Hive account (see: ''Hive Blockchain Create Extra Accounts'')
* Install Hive Keychain (browser extension)
* Log in to your account using your keys

== Buying HIVE from an Exchange ==
To obtain HBD, you will first need to buy HIVE from a cryptocurrency exchange.

Example (UK):
* https://www.mexc.com/en-GB/

Steps:
* Create and verify an account on the exchange
* Deposit funds (GBP, EUR, etc.)
* Buy HIVE

== Sending HIVE to Your Hive Account ==
Once you have purchased HIVE:

* Go to '''Withdraw''' on the exchange
* Enter your Hive username as the destination
* Double-check the username (transactions cannot be reversed)
* Send the HIVE

After a short time, the HIVE will appear in your Hive wallet.

== Swapping HIVE to HBD ==
To convert HIVE into HBD, you can use a Hive-based exchange:

* https://hivedex.io/

Steps:
* Connect your Hive account (via Hive Keychain)
* Select the HIVE → HBD market
* Enter the amount of HIVE to swap
* Confirm the transaction in Hive Keychain

Once completed, your HBD balance will be updated in your wallet.

== Notes ==
* Always verify URLs before logging in or signing transactions
* Keep your keys secure and never share them
* Test with a small amount first if you are new

And that's it — you now have HBD in your Hive account.

Hive Blockchain Create Create Extra Accounts

2026-04-19T12:33:01Z

AwesomO: Created page with "= Hive Blockchain Create Extra Accounts = == Free accounts == This is the on-ramp for your first account. https://signup.hive.io/ == Paid accounts == === Hive Keychain === * Download Hive Keychain (browser extension) * Log in with your '''Active Key''' (required to sign the ~3 HIVE account creation fee) * Click the ☰ (top left) → '''Accounts''' → '''Create Account''' * Enter a username If the username is available, you will proceed to the next stage where you..."

= Hive Blockchain Create Extra Accounts =

== Free accounts ==
This is the on-ramp for your first account.

https://signup.hive.io/

== Paid accounts ==

=== Hive Keychain ===

* Download Hive Keychain (browser extension)
* Log in with your '''Active Key''' (required to sign the ~3 HIVE account creation fee)
* Click the ☰ (top left) → '''Accounts''' → '''Create Account'''
* Enter a username

If the username is available, you will proceed to the next stage where your key pairs are shown.

'''Important:'''
When Hive Keychain is open on the key display screen, clicking outside the extension (e.g. to open a text editor) may close it. If this happens before saving, you will lose the generated keys and must restart the process.

* As soon as the keys are shown:
** Click '''Copy'''
** Tick all confirmation boxes
** Click '''Copy''' again to be safe
* Click '''Create''' to finalize the account
* Immediately paste your keys into a text file and back them up securely

And that's it — you have created a new Hive account.

Hive Blockchain Create Custom Coins

2026-04-19T12:23:06Z

AwesomO:

Hive Blockchain Create Custom Coins

2026-04-19T12:22:14Z

AwesomO: Created page with "{{LICENCE_CC0}} = v4call — How to Create Your Own Custom Token (e.g. CNOOBS) on Hive Engine = From CompleteNoobs F This guide walks you through creating a custom Hive Engine token (example: '''CNOOBS''') in under 10 minutes. No coding required. These tokens power the custom communication economy in v4call: you can set rates like "1 CNOOBS = 1 text message" or "10 CNOOBS = 1 hour video call", gift them to friends/family, or let blocked users bypass your blocklist if th..."

{{LICENCE_CC0}}
= v4call — How to Create Your Own Custom Token (e.g. CNOOBS) on Hive Engine =
From CompleteNoobs
F
This guide walks you through creating a custom Hive Engine token (example: '''CNOOBS''') in under 10 minutes. No coding required.

These tokens power the custom communication economy in v4call: you can set rates like "1 CNOOBS = 1 text message" or "10 CNOOBS = 1 hour video call", gift them to friends/family, or let blocked users bypass your blocklist if they hold enough of your token.

'''Why create your own token?'''
* Full control over supply and distribution.
* Real utility inside v4call (and any other Hive dApp that supports Hive Engine tokens).
* Scarcity you decide — perfect for personal or community communication economies.
* Transferable, tradable, and giftable via Hive Keychain or TribalDex.

'''Cost''': Approximately 100 BEE (Hive Engine's utility token). BEE price fluctuates — check current value on TribalDex or PeakD. This is a one-time creation fee.

'''Source''': Based on the official Hive Engine / TribalDex interface (as of 2026).

'''End result''': A live custom token (e.g. CNOOBS) that appears in users' Hive Keychain wallets and can be used in your v4call rates post.

== Contents ==
* [[#What_You_Need|1 What You Need]]
* [[#Step_1:_Get_Some_BEE_Tokens|2 Step 1: Get Some BEE Tokens]]
* [[#Step_2:_Log_In_to_TribalDex|3 Step 2: Log In to TribalDex]]
* [[#Step_3:_Create_Your_Token|4 Step 3: Create Your Token]]
* [[#Step_4:_Issue_Tokens_to_Yourself|5 Step 4: Issue Tokens to Yourself]]
* [[#Step_5:_Optional_-_Add_Metadata_(Logo_Description)|6 Step 5: Optional - Add Metadata (Logo & Description)]]
* [[#Step_6:_Distribute_Your_Tokens|7 Step 6: Distribute Your Tokens]]
* [[#Using_Your_Token_in_v4call|8 Using Your Token in v4call]]
* [[#Common_Problems_and_Fixes|9 Common Problems and Fixes]]
* [[#Quick_Reference|10 Quick Reference]]

== What You Need ==
* A Hive account (e.g. @noblemage) with Hive Keychain installed and the '''active key''' available.
* Some BEE tokens (≈100 BEE for creation fee).
* A web browser.

You do '''not''' need to run a node or write code.

== Step 1: Get Some BEE Tokens ==
BEE is the "gas" token for Hive Engine actions.

# Go to [https://tribaldex.com tribaldex.com] or any Hive Engine market (e.g. via PeakD wallet).
# Swap or buy BEE using HIVE or HBD (very easy with Keychain).
# Alternative: Many users get small amounts of BEE from community airdrops or by swapping on the built-in market.

Make sure you have at least 110 BEE to cover the fee plus a small buffer.

== Step 2: Log In to TribalDex ==
# Visit [https://tribaldex.com/tokens/create https://tribaldex.com/tokens/create]
# Click the login button at the top.
# Hive Keychain will pop up — approve the login with your '''active key''' (or posting key in some cases, but active is safest for token actions).

You are now logged in as your Hive account.

== Step 3: Create Your Token ==
On the token creation form, fill in the following fields carefully. Most cannot be changed later.

* '''Symbol''' — e.g. '''CNOOBS''' (uppercase, 1–10 characters, unique)
* '''Name''' — e.g. '''Cnoobs Coins'''
* '''Max Supply''' — Choose a number (e.g. 1,000,000). This is the absolute maximum that can ever exist. You can issue less.
* '''Precision''' — Usually '''3''' (allows 0.001 precision). You can only increase this later, not decrease.
* '''Website''' (optional) — Link to your profile or v4call server (e.g. https://call.yourdomain.com)
* '''Description''' (optional) — Short text like "Personal communication token for v4call — used for messages and calls with @cnoobz"

Double-check everything — the symbol especially cannot be changed.

Click '''Create Token'''.

Hive Keychain will ask you to approve a custom_json transaction. Confirm it.

Wait 3–10 seconds for confirmation on the blockchain.

Success message should appear: your token is now created!

== Step 4: Issue Tokens to Yourself ==
After creation, you usually start with zero balance.

# Go to [https://tribaldex.com/tokens/manage https://tribaldex.com/tokens/manage]
# Find your new token (CNOOBS) in the list.
# Click the '''Issue''' button.
# Enter the amount you want to issue to yourself (e.g. 10000).
# Confirm with Keychain.

You now hold the full issued supply.

== Step 5: Optional — Add Metadata (Logo & Description) ==
# Still on the manage page, click the edit icon for your token.
# Upload a square logo image (recommended 200x200 px or larger).
# Improve the description and website link.
# Save changes (another small Keychain transaction).

This makes your token look professional when users view it in wallets or markets.

== Step 6: Distribute Your Tokens ==
* Send to friends/family via Keychain → "Tokens" tab → Transfer.
* Airdrop to your community.
* Use in v4call rates (see below).
* List on TribalDex market if you want people to buy/sell them.

Tokens are fully transferable and appear instantly in recipients' Hive Keychain wallets.

== Using Your Token in v4call ==
Once you have your token:

# Go to your v4call server → /rate-editor.html
# In the rate editor (V2 format), create a new list like [LIST:token-holders]
# Set TOKEN:CNOOBS
# Define rates, e.g.:
** TEXT:1 CNOOBS
** VOICE:RING:5 CNOOBS;CONNECT:10 CNOOBS;RATE:20 CNOOBS/hr
# Your server will automatically verify balances using public Hive Engine RPC when someone tries to call or message you.

Blocked users can bypass your blocklist if you set ALLOW-IF-TOKEN:CNOOBS and they hold enough.

== Common Problems and Fixes ==
=== "Not enough BEE" error ===
Buy or swap more BEE on TribalDex.

=== Token symbol already taken ===
Choose a different symbol (add numbers or make it longer, e.g. CNOOBS2).

=== Transaction fails ===
Make sure you are using the '''active key''' in Keychain for token creation/issuing. Restart Keychain if needed.

=== Can't find my token after creation ===
Refresh the page or check https://hive-engine.com/tokens — it may take a few seconds to appear.

=== Want to issue more later? ===
You can issue up to your max supply at any time from the manage page.

== Quick Reference ==
{| class="wikitable"
|-
! Action !! Where to Do It
|-
| Create token || https://tribaldex.com/tokens/create
|-
| Manage / Issue tokens || https://tribaldex.com/tokens/manage
|-
| View all tokens || https://hive-engine.com/tokens
|-
| Swap BEE || TribalDex market
|-
| Check balance in Keychain || Hive Keychain extension → Tokens tab
|}

'''Next step for v4call users''': After creating your token, update your v4call-rates post using the improved rate-editor.html to include your custom token rates and blocklist bypass.

You now have your own personal communication currency on Hive!

[[Category:Hive]]
[[Category:Hive Engine]]
[[Category:v4call]]
[[Category:Token Creation]]
[[Category:Web3]]

Html JavaScript Cookies PopUP Accept Basic

2026-04-16T15:14:19Z

Ubuntu 24.04 WebRTC lxc Intro Basics

2026-03-28T11:17:43Z

AwesomO: Created page with "= WebRTC Video Chat on Ubuntu 24.04 with LXC — Complete Beginner's Guide = * This walk through is tested on a ubuntu-mate 24.04 host. ** Guide written with help from claude.ai for Ubuntu 24.04 LTS (Noble Numbat). Node.js 20 LTS. Last verified March 2026 This guide walks you through setting up a working browser-based WebRTC video/audio chat application. The signalling server will run inside an '''LXC container''' on your Ubuntu 24.04 host machine, and you will conne..."

= WebRTC Video Chat on Ubuntu 24.04 with LXC — Complete Beginner's Guide =

* This walk through is tested on a ubuntu-mate 24.04 host.
** Guide written with help from claude.ai for Ubuntu 24.04 LTS (Noble Numbat). Node.js 20 LTS. Last verified March 2026

This guide walks you through setting up a working browser-based WebRTC video/audio chat application. The signalling server will run inside an '''LXC container''' on your Ubuntu 24.04 host machine, and you will connect to it from your browser.

== What You Will End Up With ==

* An LXC container running Ubuntu 24.04
* A Node.js signalling server inside that container
* A static HTML/JS frontend served from the container
* Two browser tabs (or two devices on your network) that can video/audio chat peer-to-peer

== How It Works (Plain English) ==

WebRTC lets two browsers talk directly to each other for audio and video. But before they can do that, they need to '''find each other''' and '''agree on connection details'''. This is called '''signalling'''.

Think of it like two people wanting to call each other — they first need to exchange phone numbers through a third party. The signalling server is that third party. Once the call is set up, the signalling server steps aside and the browsers talk directly.

[Browser A] <--WebSocket--> [Signalling Server in LXC] <--WebSocket--> [Browser B]
|
(only used during setup)
|
[Browser A] <============ WebRTC peer-to-peer audio/video ============> [Browser B]

----

== Part 1: Set Up the LXC Container ==

=== Step 1.1 — Install LXC on Your Host ===

Open a terminal on your Ubuntu 24.04 host and run:

* <b>NOTE: you can also install lxd with snap packages on ubuntu.</b>

sudo apt update
sudo apt install lxc lxc-utils -y

Check it installed correctly:

lxc-checkconfig

You should see mostly '''enabled''' next to each item. A few '''missing''' items are normal and will not affect this guide.

=== Step 1.2 — Create the Container ===

Create a new Ubuntu 24.04 container called <code>webrtc</code>:

sudo lxc-create -n webrtc -t download -- -d ubuntu -r noble -a amd64

This downloads the Ubuntu 24.04 (Noble) image. It may take a minute or two.

=== Step 1.3 — Start the Container ===

sudo lxc-start -n webrtc

Check it is running:

sudo lxc-ls --fancy

You should see <code>webrtc</code> listed with state '''RUNNING'''.

=== Step 1.4 — Log Into the Container ===

sudo lxc-attach -n webrtc

Your prompt will change — you are now '''inside''' the container. Everything from here until told otherwise runs inside the container.

=== Step 1.5 — Update the Container ===

apt update && apt upgrade -y

----

== Part 2: Install Node.js Inside the Container ==

=== Step 2.1 — Install Node.js ===

We will use the official NodeSource repository to get a recent version of Node.js:

apt install -y curl
curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
apt install -y nodejs

Check the versions installed:

node -v
npm -v

You should see something like <code>v20.x.x</code> and <code>10.x.x</code>. Any version of Node 18 or higher is fine.

----

== Part 3: Create the Signalling Server ==

=== Step 3.1 — Create a Project Folder ===

mkdir /opt/webrtc
cd /opt/webrtc

=== Step 3.2 — Initialise the Node Project ===

npm init -y

This creates a <code>package.json</code> file. The <code>-y</code> flag just accepts all the defaults.

=== Step 3.3 — Install Dependencies ===

We need two packages:

* '''express''' — a simple web server to serve the HTML frontend
* '''socket.io''' — handles WebSocket connections for signalling

npm install express socket.io

=== Step 3.4 — Create the Server File ===

* <b>NOTE: <code>nano</code> will need to be installed in the container with <code>apt install nano -y</code></b>
Create the file:

nano server.js

Paste in the following code exactly. Use '''Ctrl+Shift+V''' to paste in the terminal:

<syntaxhighlight lang="javascript">
const express = require('express');
const http = require('http');
const { Server } = require('socket.io');
const path = require('path');

const app = express();
const server = http.createServer(app);
const io = new Server(server);

// Serve the frontend HTML file
app.use(express.static(path.join(__dirname, 'public')));

// Keep track of who is in each room
const rooms = {};

io.on('connection', (socket) => {
console.log('A user connected:', socket.id);

// User wants to join a room
socket.on('join', (room) => {
socket.join(room);

if (!rooms[room]) {
rooms[room] = [];
}

// Tell the new user who is already in the room
socket.emit('room-users', rooms[room]);

// Add this user to the room list
rooms[room].push(socket.id);

console.log(`${socket.id} joined room: ${room}`);
});

// Relay a WebRTC offer to a specific user
socket.on('offer', ({ to, offer }) => {
io.to(to).emit('offer', { from: socket.id, offer });
});

// Relay a WebRTC answer to a specific user
socket.on('answer', ({ to, answer }) => {
io.to(to).emit('answer', { from: socket.id, answer });
});

// Relay ICE candidates between peers
socket.on('ice-candidate', ({ to, candidate }) => {
io.to(to).emit('ice-candidate', { from: socket.id, candidate });
});

// Clean up when a user disconnects
socket.on('disconnect', () => {
for (const room in rooms) {
rooms[room] = rooms[room].filter((id) => id !== socket.id);
// Tell others in the room this user left
socket.to(room).emit('user-left', socket.id);
}
console.log('User disconnected:', socket.id);
});
});

const PORT = 3000;
server.listen(PORT, '0.0.0.0', () => {
console.log(`Signalling server running on port ${PORT}`);
});
</syntaxhighlight>

Save and exit: press '''Ctrl+X''', then '''Y''', then '''Enter'''.

=== Step 3.5 — Create the Frontend ===

Create a folder for the HTML file:

mkdir public
nano public/index.html

Paste in the following:

<syntaxhighlight lang="html">
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0"/>
<title>WebRTC Chat</title>
<style>
* { box-sizing: border-box; margin: 0; padding: 0; }
body { font-family: sans-serif; background: #1a1a2e; color: #eee; display: flex; flex-direction: column; align-items: center; padding: 20px; }
h1 { margin-bottom: 20px; color: #e94560; }
#join-area { margin-bottom: 20px; display: flex; gap: 10px; }
input { padding: 10px; border-radius: 6px; border: none; font-size: 1rem; width: 200px; }
button { padding: 10px 20px; background: #e94560; color: white; border: none; border-radius: 6px; cursor: pointer; font-size: 1rem; }
button:hover { background: #c73652; }
#videos { display: flex; flex-wrap: wrap; gap: 10px; justify-content: center; }
video { width: 320px; height: 240px; background: #000; border-radius: 8px; border: 2px solid #e94560; }
#status { margin-top: 15px; font-size: 0.9rem; color: #aaa; }
</style>
</head>
<body>
<h1>WebRTC Chat</h1>
<div id="join-area">
<input id="room-input" type="text" placeholder="Enter room name" value="room1" />
<button onclick="joinRoom()">Join Room</button>
</div>
<div id="videos">
<video id="local-video" autoplay muted playsinline></video>
</div>
<p id="status">Enter a room name and click Join.</p>


<script src="/socket.io/socket.io.js"></script>
<script>
const socket = io();
let localStream;
const peers = {}; // peerId -> RTCPeerConnection

// STUN server config — Google's free public STUN server
const iceConfig = {
iceServers: [{ urls: 'stun:stun.l.google.com:19302' }]
};

async function joinRoom() {
const room = document.getElementById('room-input').value.trim();
if (!room) return alert('Please enter a room name');

document.getElementById('status').textContent = 'Getting camera and microphone...';

try {
localStream = await navigator.mediaDevices.getUserMedia({ video: true, audio: true });
document.getElementById('local-video').srcObject = localStream;
} catch (err) {
alert('Could not access camera/microphone: ' + err.message);
return;
}

document.getElementById('status').textContent = `Joining room: ${room}`;
socket.emit('join', room);
}

// Server tells us who is already in the room
socket.on('room-users', async (users) => {
document.getElementById('status').textContent = `In room. ${users.length} other(s) here.`;
// Send an offer to each existing user
for (const userId of users) {
await createOffer(userId);
}
});

// A remote peer sent us an offer
socket.on('offer', async ({ from, offer }) => {
const pc = createPeerConnection(from);
await pc.setRemoteDescription(new RTCSessionDescription(offer));
const answer = await pc.createAnswer();
await pc.setLocalDescription(answer);
socket.emit('answer', { to: from, answer });
});

// A remote peer accepted our offer
socket.on('answer', async ({ from, answer }) => {
const pc = peers[from];
if (pc) await pc.setRemoteDescription(new RTCSessionDescription(answer));
});

// ICE candidate from a remote peer
socket.on('ice-candidate', async ({ from, candidate }) => {
const pc = peers[from];
if (pc && candidate) {
try { await pc.addIceCandidate(new RTCIceCandidate(candidate)); } catch (e) {}
}
});

// A user left the room
socket.on('user-left', (userId) => {
if (peers[userId]) {
peers[userId].close();
delete peers[userId];
}
const el = document.getElementById('video-' + userId);
if (el) el.remove();
document.getElementById('status').textContent = 'A user left the room.';
});

function createPeerConnection(peerId) {
const pc = new RTCPeerConnection(iceConfig);
peers[peerId] = pc;

// Add our local tracks so the remote peer gets our video/audio
localStream.getTracks().forEach((track) => pc.addTrack(track, localStream));

// When we get an ICE candidate, send it to the remote peer
pc.onicecandidate = ({ candidate }) => {
if (candidate) socket.emit('ice-candidate', { to: peerId, candidate });
};

// When we receive a remote track, display it
pc.ontrack = ({ streams }) => {
let videoEl = document.getElementById('video-' + peerId);
if (!videoEl) {
videoEl = document.createElement('video');
videoEl.id = 'video-' + peerId;
videoEl.autoplay = true;
videoEl.playsInline = true;
document.getElementById('videos').appendChild(videoEl);
}
videoEl.srcObject = streams[0];
};

return pc;
}

async function createOffer(peerId) {
const pc = createPeerConnection(peerId);
const offer = await pc.createOffer();
await pc.setLocalDescription(offer);
socket.emit('offer', { to: peerId, offer });
}
</script>
</body>
</html>
</syntaxhighlight>

Save and exit: '''Ctrl+X''', '''Y''', '''Enter'''.

----

== Part 4: Run the Server ==

=== Step 4.1 — Test it Manually First ===

Inside the container, run:

node /opt/webrtc/server.js

You should see:

Signalling server running on port 3000

Press '''Ctrl+C''' to stop it for now. We will set it up to run automatically in the next step.

=== Step 4.2 — Find the Container's IP Address ===

You need this to access the server from your host browser. Open a '''second terminal on your host''' (not inside the container) and run:

sudo lxc-ls --fancy

Look for your <code>webrtc</code> container and note the IP address in the '''IPV4''' column. It will look something like <code>10.0.3.15</code>.

=== Step 4.3 — Set Up Auto-start with systemd ===

We want the server to start automatically when the container boots. Back inside the container, create a systemd service file:

nano /etc/systemd/system/webrtc.service

Paste in:

<syntaxhighlight lang="ini">
[Unit]
Description=WebRTC Signalling Server
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/webrtc
ExecStart=/usr/bin/node /opt/webrtc/server.js
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
</syntaxhighlight>

Save and exit. Then enable and start it:

systemctl daemon-reload
systemctl enable webrtc
systemctl start webrtc

Check it is running:

systemctl status webrtc

You should see '''active (running)''' in green.

----

== Part 5: Configure the LXC Container to Auto-start ==

We also want the container itself to start when your host boots.

Exit the container first (type <code>exit</code> or press '''Ctrl+D''' to return to your host terminal), then run:

sudo nano /var/lib/lxc/webrtc/config

Add these two lines at the bottom of the file:

lxc.start.auto = 1
lxc.start.delay = 5

Save and exit. Now the container (and the signalling server inside it) will start automatically on boot.

----

== Part 6: Open the App in Your Browser ==

=== Step 6.1 — Open the App ===

On your host machine, open a browser and go to:

http://<container-ip>:3000

Replace <code><container-ip></code> with the IP address you noted in Step 4.2. For example:

http://10.0.3.15:3000

You should see the WebRTC Chat page.

=== Step 6.2 — Test With Two Browser Tabs ===

# Open the app in '''Tab 1'''. Type a room name (e.g. <code>room1</code>) and click '''Join Room'''. Allow camera and microphone access when the browser asks.
# Open the app in '''Tab 2''' (you can use a private/incognito window to get a separate camera stream). Type the '''same room name''' and click '''Join Room'''.

The two tabs should now connect and you will see two video feeds.

<div class="toccolours mw-collapsible mw-collapsed">
NOTE:If you see <code>Could not access camera/microphone: Cannot read properties of undefined (reading 'getUserMedia')</code> <div class="mw-collapsible-content">

* <b>NOTE: if you see <code>Could not access camera/microphone: Cannot read properties of undefined (reading 'getUserMedia')</code> Then you need to go to step 7 and setup HTTPS</b>

This is the HTTPS issue mentioned in Part 7. Browsers block camera/microphone access on plain http:// from non-localhost addresses — navigator.mediaDevices is simply undefined on insecure origins.

Since you're accessing via the container's IP (e.g. http://10.0.3.15:3000), the browser sees it as insecure and disables the API entirely.

Quickest fix — use mkcert on your host:While you choose — here's a quick workaround you can do right now with zero config, if you just want to test immediately:

Option: Chrome flag to allow insecure origins

Open Chrome and go to: chrome://flags/#unsafely-treat-insecure-origin-as-secure

Paste your container URL (e.g. http://10.0.3.15:3000) into the text box and enable it

Relaunch Chrome when prompted

This tells Chrome to treat that specific IP as secure, enabling getUserMedia. Only use this for local dev/testing — never on a production machine.
Firefox equivalent: go to about:config, search for media.devices.insecure.enabled and set it to true.
Once you pick your preferred HTTPS method above I'll give you the exact step-by-step commands to do it properly inside your LXC container.

</div>
</div>

=== Step 6.3 — Test From Another Device on Your Network ===

On any other device connected to the same Wi-Fi or LAN, open a browser and go to the same URL:

http://<container-ip>:3000

Join the same room name and you should connect peer-to-peer with the other browser.

'''Note:''' Camera and microphone access in browsers requires either <code>localhost</code> or a secure HTTPS connection. For testing on the same machine, <code>http://localhost</code> works fine. For other devices on your network, you may need to set up HTTPS (see Part 7).

----

== Part 7: (Optional) Enable HTTPS for Other Devices ==

Browsers block camera/microphone access on plain HTTP from non-localhost addresses. To use this from other devices on your network, you have two options:

=== Option A — Use a Self-Signed Certificate (Quick) ===

Inside the container:

apt install -y openssl
cd /opt/webrtc
openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodes -subj "/CN=localhost"

Edit <code>server.js</code> and replace the <code>http</code> section:

<syntaxhighlight lang="javascript">
const https = require('https');
const fs = require('fs');

const server = https.createServer({
key: fs.readFileSync('/opt/webrtc/key.pem'),
cert: fs.readFileSync('/opt/webrtc/cert.pem'),
}, app);
</syntaxhighlight>

<div class="toccolours mw-collapsible mw-collapsed">
Appended <code>server.js</code> file:
<div class="mw-collapsible-content">
<pre>
const express = require('express');
const https = require('https');
const { Server } = require('socket.io');
const path = require('path');

const app = express();
const fs = require('fs');

const server = https.createServer({
key: fs.readFileSync('/opt/webrtc/key.pem'),
cert: fs.readFileSync('/opt/webrtc/cert.pem'),
}, app);
const io = new Server(server);

// Serve the frontend HTML file
app.use(express.static(path.join(__dirname, 'public')));

// Keep track of who is in each room
const rooms = {};

io.on('connection', (socket) => {
console.log('A user connected:', socket.id);

// User wants to join a room
socket.on('join', (room) => {
socket.join(room);

if (!rooms[room]) {
rooms[room] = [];
}

// Tell the new user who is already in the room
socket.emit('room-users', rooms[room]);

// Add this user to the room list
rooms[room].push(socket.id);

console.log(`${socket.id} joined room: ${room}`);
});

// Relay a WebRTC offer to a specific user
socket.on('offer', ({ to, offer }) => {
io.to(to).emit('offer', { from: socket.id, offer });
});

// Relay a WebRTC answer to a specific user
socket.on('answer', ({ to, answer }) => {
io.to(to).emit('answer', { from: socket.id, answer });
});

// Relay ICE candidates between peers
socket.on('ice-candidate', ({ to, candidate }) => {
io.to(to).emit('ice-candidate', { from: socket.id, candidate });
});

// Clean up when a user disconnects
socket.on('disconnect', () => {
for (const room in rooms) {
rooms[room] = rooms[room].filter((id) => id !== socket.id);
// Tell others in the room this user left
socket.to(room).emit('user-left', socket.id);
}
console.log('User disconnected:', socket.id);
});
});

const PORT = 3000;
server.listen(PORT, '0.0.0.0', () => {
console.log(`Signalling server running on port ${PORT}`);
});

</pre>
</div>
</div>

Change <code>const http = require('http');</code> and <code>const server = http.createServer(app);</code> lines accordingly.

Restart the service:

systemctl restart webrtc

Access via:

https://<container-ip>:3000

Your browser will warn about the self-signed certificate — click '''Advanced''' and '''Proceed''' to continue.

=== Option B — Use mkcert (Trusted Certificate, Recommended) ===

<code>mkcert</code> creates locally trusted certificates without browser warnings.

On your '''host machine''':

sudo apt install mkcert
mkcert -install
mkcert <container-ip>

This creates <code><container-ip>.pem</code> and <code><container-ip>-key.pem</code>. Copy them into the container and follow the same server.js edits as Option A.

----

== Part 8: Useful Commands Reference ==

=== Managing the Container ===

{| class="wikitable"
|-
! Command !! What it does
|-
| <code>sudo lxc-start -n webrtc</code> || Start the container
|-
| <code>sudo lxc-stop -n webrtc</code> || Stop the container
|-
| <code>sudo lxc-attach -n webrtc</code> || Open a shell inside the container
|-
| <code>sudo lxc-ls --fancy</code> || List containers and their status/IP
|}

=== Managing the Server (run inside the container) ===

{| class="wikitable"
|-
! Command !! What it does
|-
| <code>systemctl status webrtc</code> || Check if the server is running
|-
| <code>systemctl restart webrtc</code> || Restart the server
|-
| <code>systemctl stop webrtc</code> || Stop the server
|-
| <code>journalctl -u webrtc -f</code> || Watch live server logs
|}

----

== Adding a ChatBox ==

* Added:
** A name input on the join screen so people aren't just "Anonymous"
** A chat panel on the right with message bubbles (your messages on the right, others on the left)
** Automatic link detection — any URL typed becomes a clickable link
** Enter to send, Shift+Enter for a newline
** A 500 character counter that turns red when you're close to the limit
** System messages when users join/leave
** A live peer count header showing how many others are in the room
** The textarea auto-resizes as you type

* Edit <code>public/index.html</code>

<div class="toccolours mw-collapsible mw-collapsed">
Appended <code>public/index.html</code>
<div class="mw-collapsible-content">
<pre>
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0"/>
<title>WebRTC Chat</title>
<link rel="preconnect" href="https://fonts.googleapis.com">
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;600&family=IBM+Plex+Sans:wght@400;500;600&display=swap" rel="stylesheet">
<style>
:root {
--bg: #0d0f14;
--surface: #161920;
--border: #252932;
--accent: #4ade80;
--accent2: #22d3ee;
--muted: #4b5263;
--text: #e2e8f0;
--subtext: #8892a4;
--self-msg: #1a2e22;
--other-msg:#161d2e;
--danger: #f87171;
}

* { box-sizing: border-box; margin: 0; padding: 0; }

body {
font-family: 'IBM Plex Sans', sans-serif;
background: var(--bg);
color: var(--text);
height: 100dvh;
display: flex;
flex-direction: column;
overflow: hidden;
}

/* ── Top bar ── */
header {
display: flex;
align-items: center;
gap: 12px;
padding: 12px 20px;
border-bottom: 1px solid var(--border);
background: var(--surface);
flex-shrink: 0;
}
header h1 {
font-family: 'IBM Plex Mono', monospace;
font-size: 1rem;
color: var(--accent);
letter-spacing: 0.05em;
}
#room-badge {
font-family: 'IBM Plex Mono', monospace;
font-size: 0.75rem;
color: var(--subtext);
background: var(--border);
padding: 2px 10px;
border-radius: 999px;
display: none;
}
#status-dot {
width: 8px; height: 8px;
border-radius: 50%;
background: var(--muted);
margin-left: auto;
flex-shrink: 0;
transition: background 0.3s;
}
#status-dot.live { background: var(--accent); box-shadow: 0 0 6px var(--accent); }

/* ── Main layout ── */
main {
display: flex;
flex: 1;
overflow: hidden;
}

/* ── Join screen ── */
#join-screen {
display: flex;
flex-direction: column;
align-items: center;
justify-content: center;
gap: 16px;
flex: 1;
padding: 40px 20px;
}
#join-screen h2 {
font-family: 'IBM Plex Mono', monospace;
font-size: 1.4rem;
color: var(--accent);
}
#join-screen p { color: var(--subtext); font-size: 0.9rem; text-align: center; max-width: 340px; }
.field-group {
display: flex;
flex-direction: column;
gap: 8px;
width: 100%;
max-width: 320px;
}
.field-group label { font-size: 0.8rem; color: var(--subtext); font-family: 'IBM Plex Mono', monospace; }
input[type="text"] {
padding: 10px 14px;
background: var(--surface);
border: 1px solid var(--border);
border-radius: 6px;
color: var(--text);
font-family: 'IBM Plex Sans', sans-serif;
font-size: 0.95rem;
width: 100%;
transition: border-color 0.2s;
outline: none;
}
input[type="text"]:focus { border-color: var(--accent); }
button.primary {
padding: 11px 24px;
background: var(--accent);
color: #0d0f14;
border: none;
border-radius: 6px;
cursor: pointer;
font-family: 'IBM Plex Mono', monospace;
font-weight: 600;
font-size: 0.9rem;
width: 100%;
max-width: 320px;
transition: opacity 0.2s, transform 0.1s;
}
button.primary:hover { opacity: 0.85; }
button.primary:active { transform: scale(0.98); }

/* ── App layout (after join) ── */
#app { display: none; flex: 1; overflow: hidden; }
#app.visible { display: flex; }

/* ── Video panel ── */
#video-panel {
display: flex;
flex-direction: column;
gap: 0;
background: #0a0c10;
border-right: 1px solid var(--border);
overflow-y: auto;
flex-shrink: 0;
width: 340px;
}
@media (max-width: 700px) {
#app.visible { flex-direction: column; }
#video-panel { width: 100%; max-height: 220px; flex-direction: row; overflow-x: auto; overflow-y: hidden; border-right: none; border-bottom: 1px solid var(--border); }
}
.video-wrapper {
position: relative;
background: #000;
}
.video-wrapper video {
width: 100%;
display: block;
aspect-ratio: 4/3;
object-fit: cover;
}
.video-label {
position: absolute;
bottom: 6px; left: 8px;
font-family: 'IBM Plex Mono', monospace;
font-size: 0.7rem;
color: #fff;
background: rgba(0,0,0,0.55);
padding: 2px 7px;
border-radius: 4px;
}

/* ── Chat panel ── */
#chat-panel {
display: flex;
flex-direction: column;
flex: 1;
overflow: hidden;
}

#chat-header {
padding: 10px 16px;
border-bottom: 1px solid var(--border);
font-family: 'IBM Plex Mono', monospace;
font-size: 0.78rem;
color: var(--subtext);
background: var(--surface);
flex-shrink: 0;
}

#messages {
flex: 1;
overflow-y: auto;
padding: 16px;
display: flex;
flex-direction: column;
gap: 10px;
scroll-behavior: smooth;
}
#messages::-webkit-scrollbar { width: 4px; }
#messages::-webkit-scrollbar-track { background: transparent; }
#messages::-webkit-scrollbar-thumb { background: var(--border); border-radius: 2px; }

/* System messages */
.msg-system {
text-align: center;
font-size: 0.75rem;
color: var(--muted);
font-family: 'IBM Plex Mono', monospace;
padding: 2px 0;
}

/* Chat bubbles */
.msg-bubble {
display: flex;
flex-direction: column;
gap: 3px;
max-width: 85%;
}
.msg-bubble.self { align-self: flex-end; align-items: flex-end; }
.msg-bubble.other { align-self: flex-start; align-items: flex-start; }

.msg-meta {
font-size: 0.7rem;
color: var(--subtext);
font-family: 'IBM Plex Mono', monospace;
padding: 0 4px;
}
.msg-bubble.self .msg-meta { color: var(--accent); }

.msg-text {
padding: 9px 13px;
border-radius: 12px;
font-size: 0.9rem;
line-height: 1.5;
word-break: break-word;
}
.msg-bubble.self .msg-text {
background: var(--self-msg);
border: 1px solid rgba(74,222,128,0.2);
border-bottom-right-radius: 3px;
}
.msg-bubble.other .msg-text {
background: var(--other-msg);
border: 1px solid var(--border);
border-bottom-left-radius: 3px;
}

/* Links inside messages */
.msg-text a {
color: var(--accent2);
text-decoration: underline;
text-underline-offset: 2px;
word-break: break-all;
}
.msg-text a:hover { opacity: 0.8; }

/* ── Input bar ── */
#input-bar {
display: flex;
gap: 8px;
padding: 12px 16px;
border-top: 1px solid var(--border);
background: var(--surface);
flex-shrink: 0;
}
#msg-input {
flex: 1;
padding: 10px 14px;
background: var(--bg);
border: 1px solid var(--border);
border-radius: 8px;
color: var(--text);
font-family: 'IBM Plex Sans', sans-serif;
font-size: 0.9rem;
outline: none;
resize: none;
height: 42px;
max-height: 120px;
overflow-y: auto;
transition: border-color 0.2s;
}
#msg-input:focus { border-color: var(--accent); }
#send-btn {
padding: 0 16px;
background: var(--accent);
color: #0d0f14;
border: none;
border-radius: 8px;
cursor: pointer;
font-family: 'IBM Plex Mono', monospace;
font-weight: 600;
font-size: 0.85rem;
flex-shrink: 0;
transition: opacity 0.2s;
}
#send-btn:hover { opacity: 0.85; }
#char-count {
font-size: 0.7rem;
color: var(--muted);
font-family: 'IBM Plex Mono', monospace;
align-self: flex-end;
padding-bottom: 4px;
flex-shrink: 0;
width: 36px;
text-align: right;
}
#char-count.warn { color: var(--danger); }
</style>
</head>
<body>

<header>
<h1>// webrtc</h1>
<span id="room-badge"></span>
<div id="status-dot" title="Connecting..."></div>
</header>


<div id="join-screen">
<h2>join a room</h2>
<p>Enter your name and a room name. Anyone with the same room name will connect with you.</p>
<div class="field-group">
<label>YOUR NAME</label>
<input id="name-input" type="text" placeholder="e.g. Alice" maxlength="24" />
</div>
<div class="field-group">
<label>ROOM NAME</label>
<input id="room-input" type="text" placeholder="e.g. room1" value="room1" maxlength="32" />
</div>
<button class="primary" onclick="joinRoom()">Join Room →</button>
</div>


<main>
<div id="app">


<div id="video-panel">
<div class="video-wrapper" id="local-wrapper">
<video id="local-video" autoplay muted playsinline></video>
<div class="video-label" id="local-label">you</div>
</div>
</div>


<div id="chat-panel">
<div id="chat-header">MESSAGES — <span id="peer-count">0 others in room</span></div>
<div id="messages">
<div class="msg-system">Chat is end-to-end via your server. Video is peer-to-peer.</div>
</div>
<div id="input-bar">
<textarea id="msg-input" placeholder="Type a message… (Enter to send, Shift+Enter for newline)" rows="1"></textarea>
<span id="char-count">500</span>
<button id="send-btn" onclick="sendMessage()">Send</button>
</div>
</div>

</div>
</main>

<script src="/socket.io/socket.io.js"></script>
<script>
const socket = io();
let localStream;
let myName = 'Anonymous';
let currentRoom = '';
let peerCount = 0;
const peers = {};
const MAX_MSG = 500;

const iceConfig = {
iceServers: [{ urls: 'stun:stun.l.google.com:19302' }]
};

// ── Helpers ──────────────────────────────────────────────

// Detect URLs in text and wrap them in <a> tags
function linkify(text) {
const escaped = text
.replace(/&/g, '&')
.replace(/</g, '<')
.replace(/>/g, '>');
const urlRegex = /(https?:\/\/[^\s<>"]+)/g;
return escaped.replace(urlRegex, '<a href="$1" target="_blank" rel="noopener noreferrer">$1</a>');
}

function addMessage({ name, message, isSelf, isSystem }) {
const container = document.getElementById('messages');

if (isSystem) {
const el = document.createElement('div');
el.className = 'msg-system';
el.textContent = message;
container.appendChild(el);
} else {
const bubble = document.createElement('div');
bubble.className = 'msg-bubble ' + (isSelf ? 'self' : 'other');

const now = new Date().toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' });
const meta = document.createElement('div');
meta.className = 'msg-meta';
meta.textContent = (isSelf ? 'you' : name) + ' · ' + now;

const body = document.createElement('div');
body.className = 'msg-text';
// Linkify and preserve newlines
body.innerHTML = linkify(message).replace(/\n/g, '<br>');

bubble.appendChild(meta);
bubble.appendChild(body);
container.appendChild(bubble);
}

// Auto-scroll to bottom
container.scrollTop = container.scrollHeight;
}

function updatePeerCount() {
document.getElementById('peer-count').textContent =
peerCount === 0 ? 'no others in room yet'
: peerCount === 1 ? '1 other in room'
: `${peerCount} others in room`;
}

// ── Join ─────────────────────────────────────────────────

async function joinRoom() {
const nameVal = document.getElementById('name-input').value.trim();
const roomVal = document.getElementById('room-input').value.trim();

if (!roomVal) { alert('Please enter a room name'); return; }
myName = nameVal || 'Anonymous';
currentRoom = roomVal;

try {
localStream = await navigator.mediaDevices.getUserMedia({ video: true, audio: true });
document.getElementById('local-video').srcObject = localStream;
document.getElementById('local-label').textContent = myName + ' (you)';
} catch (err) {
alert('Could not access camera/microphone: ' + err.message);
return;
}

document.getElementById('join-screen').style.display = 'none';
document.getElementById('app').classList.add('visible');
document.getElementById('room-badge').textContent = '# ' + currentRoom;
document.getElementById('room-badge').style.display = '';
document.getElementById('status-dot').classList.add('live');

socket.emit('join', currentRoom);
addMessage({ isSystem: true, message: `You joined #${currentRoom} as "${myName}"` });
updatePeerCount();
}

// ── Chat ─────────────────────────────────────────────────

function sendMessage() {
const input = document.getElementById('msg-input');
const text = input.value.trim();
if (!text || !currentRoom) return;
if (text.length > MAX_MSG) { alert(`Max ${MAX_MSG} characters`); return; }

socket.emit('chat-message', { room: currentRoom, message: text, name: myName });
addMessage({ name: myName, message: text, isSelf: true });

input.value = '';
input.style.height = '42px';
document.getElementById('char-count').textContent = MAX_MSG;
document.getElementById('char-count').classList.remove('warn');
}

socket.on('chat-message', ({ name, message }) => {
addMessage({ name, message, isSelf: false });
});

// Enter to send, Shift+Enter for newline
document.getElementById('msg-input').addEventListener('keydown', (e) => {
if (e.key === 'Enter' && !e.shiftKey) {
e.preventDefault();
sendMessage();
}
});

// Char counter + auto-resize textarea
document.getElementById('msg-input').addEventListener('input', function () {
const remaining = MAX_MSG - this.value.length;
const counter = document.getElementById('char-count');
counter.textContent = remaining;
counter.classList.toggle('warn', remaining < 50);
this.style.height = '42px';
this.style.height = Math.min(this.scrollHeight, 120) + 'px';
});

// ── WebRTC ───────────────────────────────────────────────

socket.on('room-users', async (users) => {
peerCount = users.length;
updatePeerCount();
for (const userId of users) {
await createOffer(userId);
}
});

socket.on('offer', async ({ from, offer }) => {
const pc = createPeerConnection(from);
await pc.setRemoteDescription(new RTCSessionDescription(offer));
const answer = await pc.createAnswer();
await pc.setLocalDescription(answer);
socket.emit('answer', { to: from, answer });
});

socket.on('answer', async ({ from, answer }) => {
const pc = peers[from];
if (pc) await pc.setRemoteDescription(new RTCSessionDescription(answer));
});

socket.on('ice-candidate', async ({ from, candidate }) => {
const pc = peers[from];
if (pc && candidate) {
try { await pc.addIceCandidate(new RTCIceCandidate(candidate)); } catch (e) {}
}
});

socket.on('user-left', (userId) => {
if (peers[userId]) { peers[userId].close(); delete peers[userId]; }
const el = document.getElementById('video-' + userId);
if (el) el.closest('.video-wrapper').remove();
peerCount = Math.max(0, peerCount - 1);
updatePeerCount();
addMessage({ isSystem: true, message: 'A user left the room.' });
});

function createPeerConnection(peerId) {
const pc = new RTCPeerConnection(iceConfig);
peers[peerId] = pc;

localStream.getTracks().forEach((track) => pc.addTrack(track, localStream));

pc.onicecandidate = ({ candidate }) => {
if (candidate) socket.emit('ice-candidate', { to: peerId, candidate });
};

pc.ontrack = ({ streams }) => {
let wrapper = document.getElementById('wrapper-' + peerId);
if (!wrapper) {
wrapper = document.createElement('div');
wrapper.className = 'video-wrapper';
wrapper.id = 'wrapper-' + peerId;

const vid = document.createElement('video');
vid.id = 'video-' + peerId;
vid.autoplay = true;
vid.playsInline = true;

const label = document.createElement('div');
label.className = 'video-label';
label.textContent = 'peer';

wrapper.appendChild(vid);
wrapper.appendChild(label);
document.getElementById('video-panel').appendChild(wrapper);

peerCount = Object.keys(peers).length;
updatePeerCount();
}
document.getElementById('video-' + peerId).srcObject = streams[0];
};

return pc;
}

async function createOffer(peerId) {
const pc = createPeerConnection(peerId);
const offer = await pc.createOffer();
await pc.setLocalDescription(offer);
socket.emit('offer', { to: peerId, offer });
}
</script>
</body>
</html>

</pre>
</div>
</div>

* Edit <code>server.js</code>
<div class="toccolours mw-collapsible mw-collapsed">
Appended <b>server.js</b>
<div class="mw-collapsible-content">

<pre>
const express = require('express');
const https = require('https');
const { Server } = require('socket.io');
const path = require('path');

const app = express();
const fs = require('fs');

const server = https.createServer({
key: fs.readFileSync('/opt/webrtc/key.pem'),
cert: fs.readFileSync('/opt/webrtc/cert.pem'),
}, app);
const io = new Server(server);

// Serve the frontend HTML file
app.use(express.static(path.join(__dirname, 'public')));

// Keep track of who is in each room
const rooms = {};

io.on('connection', (socket) => {
console.log('A user connected:', socket.id);

// User wants to join a room
socket.on('join', (room) => {
socket.join(room);

if (!rooms[room]) {
rooms[room] = [];
}

// Tell the new user who is already in the room
socket.emit('room-users', rooms[room]);

// Add this user to the room list
rooms[room].push(socket.id);

console.log(`${socket.id} joined room: ${room}`);
});

// Relay a WebRTC offer to a specific user
socket.on('offer', ({ to, offer }) => {
io.to(to).emit('offer', { from: socket.id, offer });
});

// Relay a WebRTC answer to a specific user
socket.on('answer', ({ to, answer }) => {
io.to(to).emit('answer', { from: socket.id, answer });
});

// Relay ICE candidates between peers
socket.on('ice-candidate', ({ to, candidate }) => {
io.to(to).emit('ice-candidate', { from: socket.id, candidate });
});

// ---- CHAT ----
// Relay a chat message to everyone else in the room
socket.on('chat-message', ({ room, message, name }) => {
// Broadcast to everyone in the room EXCEPT the sender
socket.to(room).emit('chat-message', {
from: socket.id,
name: name || 'Anonymous',
message,
time: new Date().toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })
});
});
// ---- END CHAT ----

// Clean up when a user disconnects
socket.on('disconnect', () => {
for (const room in rooms) {
rooms[room] = rooms[room].filter((id) => id !== socket.id);
// Tell others in the room this user left
socket.to(room).emit('user-left', socket.id);
}
console.log('User disconnected:', socket.id);
});
});

const PORT = 3000;
server.listen(PORT, '0.0.0.0', () => {
console.log(`Signalling server running on port ${PORT}`);
});

</pre>
</div>
</div>

* Restart webrtc: <code>systemctl restart webrtc</code>

Test - Should be working

== Troubleshooting ==

=== "Cannot connect to the page" ===
* Make sure the container is running: <code>sudo lxc-ls --fancy</code>
* Make sure the service is running: attach to the container and run <code>systemctl status webrtc</code>
* Double-check the IP address — it can change after a container restart. Assign a static IP via LXC config if needed.

=== "Camera/Microphone access denied" ===
* On non-localhost addresses, browsers require HTTPS. See Part 7.
* Make sure you clicked '''Allow''' (not Block) when the browser asked for permissions.
* Try in a different browser, or clear site permissions in browser settings.

=== Two tabs connect but no video appears ===
* This usually means ICE negotiation is failing. For local testing this should not happen.
* If testing across networks (not just local LAN), you will need a '''TURN server''' (e.g. coturn). This is beyond the scope of this guide.

=== Port 3000 not reachable ===
* Check no firewall is blocking it on the host: <code>sudo ufw status</code>
* LXC containers on the default <code>lxcbr0</code> bridge are reachable from the host by default. No port forwarding should be needed for local access.

User:ChandraArgueta

2026-01-06T20:23:02Z

AwesomO: Blanked the page

User:StephaniaEberhar

2026-01-06T20:22:16Z

AwesomO: Blanked the page

User:ReinaldoTonga76

2026-01-06T20:21:40Z

AwesomO: Blanked the page

Why New 18 Video Platforms Are Improving The User Experience

2026-01-06T20:21:05Z

AwesomO: Blanked the page

CompleteNoobs Docker Image 2

2025-09-02T14:46:21Z

AwesomO: /* 5.2: Test Extensions */

==todo==
* Use Dir for import export of xml.
* Min scripts - just setup mediawiki with extensions.

= Complete Noobs Docker Wiki Tutorial v0.2 =
* Version 0.2 - Simplified with manual import/export
* [[Docker_Install_Guide| Docker install guide]]

== Overview ==
This tutorial creates a MediaWiki Docker container with:
* MediaWiki 1.44
* PageNotice extension (for license notices)
* YouTube extension (for video embedding)
* Shared directory for XML import/export

== Prerequisites ==
* Ubuntu 24.04
* Docker installed and running
* Your user in docker group: <code>sudo usermod -aG docker $USER</code> (then logout/login)

== Step 1: Create Directory Structure ==

=== 1.1: Create Project Directory ===
<syntaxhighlight lang="bash">
mkdir ~/completenoobs-docker-v2
cd ~/completenoobs-docker-v2
</syntaxhighlight>

=== 1.2: Create Shared Directory ===
<syntaxhighlight lang="bash">
mkdir ~/wiki-container
</syntaxhighlight>
This directory will be used for importing and exporting XML files.

== Step 2: Create All Files ==

=== 2.1: Dockerfile ===
<syntaxhighlight lang="bash">
nano Dockerfile
</syntaxhighlight>

<syntaxhighlight lang="dockerfile">
FROM mediawiki:1.44

# Install dependencies
RUN apt-get update && apt-get install -y \
mariadb-server \
python3-pygments \
curl \
wget \
unzip \
nano \
vim \
git \
&& apt-get clean

# Copy setup script
COPY setup_wiki.sh /usr/src/setup_wiki.sh
COPY entrypoint.sh /entrypoint.sh

# Make executable
RUN chmod +x /usr/src/setup_wiki.sh /entrypoint.sh

# Setup wiki
RUN /usr/src/setup_wiki.sh

EXPOSE 80
VOLUME /var/lib/mysql
VOLUME /var/www/html/images
VOLUME /export

ENTRYPOINT ["/entrypoint.sh"]
</syntaxhighlight>

=== 2.2: Main Setup Script ===
<syntaxhighlight lang="bash">
nano setup_wiki.sh
</syntaxhighlight>

<syntaxhighlight lang="bash">
#!/bin/bash
set -e

echo "Setting up CompleteNoobs Wiki..."

# Initialize MariaDB
if [ ! -d "/var/lib/mysql/mysql" ]; then
mysql_install_db --user=mysql --datadir=/var/lib/mysql
fi

service mariadb start

# Wait for MariaDB
for i in {1..30}; do
if mysql -e "SELECT 1;" &>/dev/null; then
echo "MariaDB ready!"
break
fi
sleep 2
done

# Setup database
mysql -e "CREATE DATABASE IF NOT EXISTS completenoobs_wiki CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
mysql -e "CREATE USER IF NOT EXISTS 'wikiuser'@'127.0.0.1' IDENTIFIED BY 'wikipass';"
mysql -e "GRANT ALL PRIVILEGES ON completenoobs_wiki.* TO 'wikiuser'@'127.0.0.1';"
mysql -e "CREATE USER IF NOT EXISTS 'wikiuser'@'localhost' IDENTIFIED BY 'wikipass';"
mysql -e "GRANT ALL PRIVILEGES ON completenoobs_wiki.* TO 'wikiuser'@'localhost';"
mysql -e "FLUSH PRIVILEGES;"

# Install MediaWiki
cd /var/www/html
php maintenance/install.php \
--dbtype=mysql \
--dbserver=127.0.0.1 \
--dbname=completenoobs_wiki \
--dbuser=wikiuser \
--dbpass=wikipass \
--server="http://localhost:8080" \
--scriptpath="" \
--lang=en \
--pass=AdminPass123! \
"CompleteNoobs Wiki" \
"admin"

# Download and install extensions
cd extensions/
echo "Installing PageNotice extension..."
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/PageNotice --branch REL1_44 || echo "PageNotice download failed, continuing..."

echo "Installing YouTube extension..."
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/YouTube --branch REL1_44 || echo "YouTube download failed, continuing..."

cd /var/www/html

# Configure LocalSettings.php
cat >> LocalSettings.php << 'EOF'

# Basic settings
$wgEnableUploads = true;
$wgUseImageMagick = true;
$wgImageMagickConvertCommand = "/usr/bin/convert";
$wgDefaultSkin = "vector-2022";
$wgAllowExternalImages = true;

# Debug settings (remove in production)
$wgShowExceptionDetails = true;
$wgDebugLogFile = "/tmp/mediawiki-debug.log";

# PageNotice extension
if ( file_exists( "$IP/extensions/PageNotice/extension.json" ) ) {
wfLoadExtension( 'PageNotice' );
}

# YouTube extension
if ( file_exists( "$IP/extensions/YouTube/extension.json" ) ) {
wfLoadExtension( 'YouTube' );
}

# SyntaxHighlight (usually bundled)
if ( file_exists( "$IP/extensions/SyntaxHighlight_GeSHi/extension.json" ) ) {
wfLoadExtension( 'SyntaxHighlight_GeSHi' );
$wgPygmentizePath = '/usr/bin/pygmentize';
}
EOF

# Create helper scripts
cat > /var/www/html/export_wiki.sh << 'EXPORT_EOF'
#!/bin/bash
echo "=== Wiki Export Tool ==="
DATE=$(date +%Y%m%d)
OUTPUT_FILE="/export/${DATE}_wiki_export.xml"

echo "Exporting wiki to: $OUTPUT_FILE"
php /var/www/html/maintenance/run.php dumpBackup.php --full --output=file:$OUTPUT_FILE

if [ -f "$OUTPUT_FILE" ]; then
echo "Export successful!"
echo "File saved to: $OUTPUT_FILE"
echo "On host system: ~/wiki-container/${DATE}_wiki_export.xml"
else
echo "Export failed!"
fi
EXPORT_EOF
chmod +x /var/www/html/export_wiki.sh

cat > /var/www/html/import_wiki.sh << 'IMPORT_EOF'
#!/bin/bash
echo "=== Wiki Import Tool ==="
echo ""
echo "Available XML files in /export:"
ls -la /export/*.xml 2>/dev/null || echo "No XML files found"
echo ""

if [ -z "$1" ]; then
echo "Usage: /var/www/html/import_wiki.sh <filename>"
echo "Example: /var/www/html/import_wiki.sh /export/wiki.xml"
exit 1
fi

if [ ! -f "$1" ]; then
echo "Error: File $1 not found!"
exit 1
fi

echo "Importing from: $1"
echo "This may take several minutes..."

php /var/www/html/maintenance/run.php importDump.php "$1"

if [ $? -eq 0 ]; then
echo "Import completed!"
echo "Rebuilding indexes..."
php /var/www/html/maintenance/run.php rebuildrecentchanges.php
php /var/www/html/maintenance/run.php initSiteStats.php
echo "Done!"
else
echo "Import failed! Check /tmp/mediawiki-debug.log for details"
fi
IMPORT_EOF
chmod +x /var/www/html/import_wiki.sh

# Create status check script
cat > /var/www/html/check_status.sh << 'STATUS_EOF'
#!/bin/bash
cd /var/www/html
echo "=== Wiki Status ==="
echo "Pages: $(mysql --user=wikiuser --password=wikipass completenoobs_wiki -e "SELECT COUNT(*) FROM page;" -s -N 2>/dev/null || echo "Error")"
echo "Users: $(mysql --user=wikiuser --password=wikipass completenoobs_wiki -e "SELECT COUNT(*) FROM user WHERE user_id > 0;" -s -N 2>/dev/null || echo "Error")"
echo ""
echo "=== Extensions ==="
if [ -d "extensions/PageNotice" ]; then
echo "PageNotice: Installed ✓"
else
echo "PageNotice: Not installed ✗"
fi
if [ -d "extensions/YouTube" ]; then
echo "YouTube: Installed ✓"
else
echo "YouTube: Not installed ✗"
fi
if [ -d "extensions/SyntaxHighlight_GeSHi" ]; then
echo "SyntaxHighlight: Installed ✓"
else
echo "SyntaxHighlight: Not installed ✗"
fi
echo ""
echo "=== Shared Directory ==="
if [ -d "/export" ]; then
echo "/export mounted ✓"
echo "Files in /export:"
ls -la /export/*.xml 2>/dev/null || echo " No XML files"
else
echo "/export not mounted ✗"
fi
STATUS_EOF
chmod +x /var/www/html/check_status.sh

echo ""
echo "Setup completed!"
echo "Admin: admin / AdminPass123!"

service mariadb stop
</syntaxhighlight>

=== 2.3: Entrypoint Script ===
<syntaxhighlight lang="bash">
nano entrypoint.sh
</syntaxhighlight>

<syntaxhighlight lang="bash">
#!/bin/bash

echo "Starting CompleteNoobs Wiki..."

service mariadb start

# Wait for MariaDB
for i in {1..30}; do
if mysql -e "SELECT 1;" &>/dev/null; then
echo "MariaDB ready!"
break
fi
sleep 1
done

echo ""
echo "========================================="
echo "CompleteNoobs Wiki v0.2 Ready!"
echo "========================================="
echo ""
echo "Access: http://localhost:8080"
echo "Admin: admin / AdminPass123!"
echo ""
echo "Features:"
echo "- MediaWiki 1.44"
echo "- PageNotice extension"
echo "- YouTube extension"
echo "- SyntaxHighlight extension"
echo "- Import/Export via ~/wiki-container"
echo ""
echo "Available commands:"
echo "- Export wiki: docker exec completenoobs_wiki /var/www/html/export_wiki.sh"
echo "- Import XML: docker exec completenoobs_wiki /var/www/html/import_wiki.sh /export/filename.xml"
echo "- Check status: docker exec completenoobs_wiki /var/www/html/check_status.sh"
echo ""

apache2-foreground
</syntaxhighlight>

== Step 3: Build and Run ==

=== 3.1: Build the Image ===
<syntaxhighlight lang="bash">
docker build -t completenoobs/wiki:v0.2 .
</syntaxhighlight>

=== 3.2: Run the Container with Shared Directory ===
<syntaxhighlight lang="bash">
docker run -d -p 8080:80 \
-v ~/wiki-container:/export \
-v completenoobs_mysql:/var/lib/mysql \
-v completenoobs_images:/var/www/html/images \
--name completenoobs_wiki \
completenoobs/wiki:v0.2
</syntaxhighlight>

== Step 4: Import/Export Operations ==

=== 4.1: Import an XML File ===
* https://xml.completenoobs.com/xmlDumps/
==== Place XML file in shared directory ====
<syntaxhighlight lang="bash">
# Copy your XML file to the shared directory
cp ~/Downloads/completenoobs.xml ~/wiki-container/
</syntaxhighlight>

==== Import the file ====
* All files in host <code>wiki-container</code> directory will also be in the containers <code>/export/</code> directory.
<syntaxhighlight lang="bash">
# Run the import command
docker exec completenoobs_wiki /var/www/html/import_wiki.sh /export/completenoobs.xml
</syntaxhighlight>

{{:Restore_the_completenoobs_Main_Page}}

=== 4.2: Export Your Wiki ===
<syntaxhighlight lang="bash">
# Export wiki to dated XML file
docker exec completenoobs_wiki /var/www/html/export_wiki.sh

# Check the exported file
ls -la ~/wiki-container/
</syntaxhighlight>

=== 4.3: Manual Import/Export (Advanced) ===

==== Access container shell ====
<syntaxhighlight lang="bash">
docker exec -it completenoobs_wiki bash
</syntaxhighlight>

==== Manual export with custom filename ====
<syntaxhighlight lang="bash">
php /var/www/html/maintenance/run.php dumpBackup.php --full --output=file:/export/my_wiki_backup.xml
exit
</syntaxhighlight>

==== Manual import with options ====
<syntaxhighlight lang="bash">
# Basic import
php /var/www/html/maintenance/run.php importDump.php /export/wiki.xml

# Import with image uploads
php /var/www/html/maintenance/run.php importDump.php --uploads /export/wiki.xml

# Then rebuild indexes
php /var/www/html/maintenance/run.php rebuildall.php
exit
</syntaxhighlight>

== Step 5: Testing and Verification ==

=== 5.1: Check Wiki Status ===
<syntaxhighlight lang="bash">
docker exec completenoobs_wiki /var/www/html/check_status.sh
</syntaxhighlight>

=== 5.2: Test Extensions ===
1. Visit http://localhost:8080
2. Login with admin / AdminPass123!
3. Create or edit a page and test:
* YouTube: Add/Test <nowiki><youtube>gBML6zuUpK0</youtube></nowiki> <code><youtube>gBML6zuUpK0</youtube></code>
* SyntaxHighlight: Add <nowiki><syntaxhighlight lang="python">print("Hello")</syntaxhighlight></nowiki>

=== 5.3: View Logs ===
<syntaxhighlight lang="bash">
# Container logs
docker logs completenoobs_wiki

# MediaWiki debug log
docker exec completenoobs_wiki tail -f /tmp/mediawiki-debug.log
</syntaxhighlight>

== Step 6: Common Operations ==

=== 6.1: Change Admin Password ===

==== Via Web Interface ====
1. Login at http://localhost:8080
2. Click username → Preferences
3. Go to Password tab
4. Change password

==== Via Terminal ====
<syntaxhighlight lang="bash">
docker exec -it completenoobs_wiki bash
php /var/www/html/maintenance/run.php changePassword.php --user=admin --password=NEWPASSWORD
exit
</syntaxhighlight>

=== 6.2: Backup Your Wiki ===
<syntaxhighlight lang="bash">
# Create dated backup
docker exec completenoobs_wiki /var/www/html/export_wiki.sh

# Copy to safe location
cp ~/wiki-container/*_wiki_export.xml ~/backups/
</syntaxhighlight>

=== 6.3: Restore from Backup ===
<syntaxhighlight lang="bash">
# Place backup in shared directory
cp ~/backups/20250101_wiki_export.xml ~/wiki-container/

# Import the backup
docker exec completenoobs_wiki /var/www/html/import_wiki.sh /export/20250101_wiki_export.xml
</syntaxhighlight>

=== 6.4: Complete Reset ===
<syntaxhighlight lang="bash">
# Stop and remove container
docker stop completenoobs_wiki
docker rm completenoobs_wiki

# Remove volumes (WARNING: This deletes all data!)
docker volume rm completenoobs_mysql completenoobs_images

# Rebuild and start fresh
docker run -d -p 8080:80 \
-v ~/wiki-container:/export \
-v completenoobs_mysql:/var/lib/mysql \
-v completenoobs_images:/var/www/html/images \
--name completenoobs_wiki \
completenoobs/wiki:v0.2
</syntaxhighlight>

== Troubleshooting ==

=== Permission Issues ===
If you encounter permission errors with the shared directory:
<syntaxhighlight lang="bash">
# Fix permissions on host
chmod 777 ~/wiki-container
</syntaxhighlight>

=== Import Failures ===
If imports fail, check:
* File exists in ~/wiki-container
* File is valid XML format
* Sufficient disk space
* Check debug log: <code>docker exec completenoobs_wiki tail /tmp/mediawiki-debug.log</code>

=== Container Won't Start ===
<syntaxhighlight lang="bash">
# Check logs
docker logs completenoobs_wiki

# Try interactive mode
docker run -it --rm completenoobs/wiki:v0.2 bash
</syntaxhighlight>

== Summary ==
This setup provides:
* Clean MediaWiki 1.44 installation
* Essential extensions (PageNotice, YouTube, SyntaxHighlight)
* Simple import/export via ~/wiki-container directory
* No automatic updates - full control over your content
* Easy backup and restore capabilities

The shared directory approach gives you complete control over when and what to import/export, making it ideal for:
* Migrating content between wikis
* Regular backups
* Sharing wiki content
* Testing imports before applying to production

CompleteNoobs Docker Image 2

2025-09-02T14:42:36Z

AwesomO: /* 5.2: Test Extensions */

==todo==
* Use Dir for import export of xml.
* Min scripts - just setup mediawiki with extensions.

= Complete Noobs Docker Wiki Tutorial v0.2 =
* Version 0.2 - Simplified with manual import/export
* [[Docker_Install_Guide| Docker install guide]]

== Overview ==
This tutorial creates a MediaWiki Docker container with:
* MediaWiki 1.44
* PageNotice extension (for license notices)
* YouTube extension (for video embedding)
* Shared directory for XML import/export

== Prerequisites ==
* Ubuntu 24.04
* Docker installed and running
* Your user in docker group: <code>sudo usermod -aG docker $USER</code> (then logout/login)

== Step 1: Create Directory Structure ==

=== 1.1: Create Project Directory ===
<syntaxhighlight lang="bash">
mkdir ~/completenoobs-docker-v2
cd ~/completenoobs-docker-v2
</syntaxhighlight>

=== 1.2: Create Shared Directory ===
<syntaxhighlight lang="bash">
mkdir ~/wiki-container
</syntaxhighlight>
This directory will be used for importing and exporting XML files.

== Step 2: Create All Files ==

=== 2.1: Dockerfile ===
<syntaxhighlight lang="bash">
nano Dockerfile
</syntaxhighlight>

<syntaxhighlight lang="dockerfile">
FROM mediawiki:1.44

# Install dependencies
RUN apt-get update && apt-get install -y \
mariadb-server \
python3-pygments \
curl \
wget \
unzip \
nano \
vim \
git \
&& apt-get clean

# Copy setup script
COPY setup_wiki.sh /usr/src/setup_wiki.sh
COPY entrypoint.sh /entrypoint.sh

# Make executable
RUN chmod +x /usr/src/setup_wiki.sh /entrypoint.sh

# Setup wiki
RUN /usr/src/setup_wiki.sh

EXPOSE 80
VOLUME /var/lib/mysql
VOLUME /var/www/html/images
VOLUME /export

ENTRYPOINT ["/entrypoint.sh"]
</syntaxhighlight>

=== 2.2: Main Setup Script ===
<syntaxhighlight lang="bash">
nano setup_wiki.sh
</syntaxhighlight>

<syntaxhighlight lang="bash">
#!/bin/bash
set -e

echo "Setting up CompleteNoobs Wiki..."

# Initialize MariaDB
if [ ! -d "/var/lib/mysql/mysql" ]; then
mysql_install_db --user=mysql --datadir=/var/lib/mysql
fi

service mariadb start

# Wait for MariaDB
for i in {1..30}; do
if mysql -e "SELECT 1;" &>/dev/null; then
echo "MariaDB ready!"
break
fi
sleep 2
done

# Setup database
mysql -e "CREATE DATABASE IF NOT EXISTS completenoobs_wiki CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
mysql -e "CREATE USER IF NOT EXISTS 'wikiuser'@'127.0.0.1' IDENTIFIED BY 'wikipass';"
mysql -e "GRANT ALL PRIVILEGES ON completenoobs_wiki.* TO 'wikiuser'@'127.0.0.1';"
mysql -e "CREATE USER IF NOT EXISTS 'wikiuser'@'localhost' IDENTIFIED BY 'wikipass';"
mysql -e "GRANT ALL PRIVILEGES ON completenoobs_wiki.* TO 'wikiuser'@'localhost';"
mysql -e "FLUSH PRIVILEGES;"

# Install MediaWiki
cd /var/www/html
php maintenance/install.php \
--dbtype=mysql \
--dbserver=127.0.0.1 \
--dbname=completenoobs_wiki \
--dbuser=wikiuser \
--dbpass=wikipass \
--server="http://localhost:8080" \
--scriptpath="" \
--lang=en \
--pass=AdminPass123! \
"CompleteNoobs Wiki" \
"admin"

# Download and install extensions
cd extensions/
echo "Installing PageNotice extension..."
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/PageNotice --branch REL1_44 || echo "PageNotice download failed, continuing..."

echo "Installing YouTube extension..."
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/YouTube --branch REL1_44 || echo "YouTube download failed, continuing..."

cd /var/www/html

# Configure LocalSettings.php
cat >> LocalSettings.php << 'EOF'

# Basic settings
$wgEnableUploads = true;
$wgUseImageMagick = true;
$wgImageMagickConvertCommand = "/usr/bin/convert";
$wgDefaultSkin = "vector-2022";
$wgAllowExternalImages = true;

# Debug settings (remove in production)
$wgShowExceptionDetails = true;
$wgDebugLogFile = "/tmp/mediawiki-debug.log";

# PageNotice extension
if ( file_exists( "$IP/extensions/PageNotice/extension.json" ) ) {
wfLoadExtension( 'PageNotice' );
}

# YouTube extension
if ( file_exists( "$IP/extensions/YouTube/extension.json" ) ) {
wfLoadExtension( 'YouTube' );
}

# SyntaxHighlight (usually bundled)
if ( file_exists( "$IP/extensions/SyntaxHighlight_GeSHi/extension.json" ) ) {
wfLoadExtension( 'SyntaxHighlight_GeSHi' );
$wgPygmentizePath = '/usr/bin/pygmentize';
}
EOF

# Create helper scripts
cat > /var/www/html/export_wiki.sh << 'EXPORT_EOF'
#!/bin/bash
echo "=== Wiki Export Tool ==="
DATE=$(date +%Y%m%d)
OUTPUT_FILE="/export/${DATE}_wiki_export.xml"

echo "Exporting wiki to: $OUTPUT_FILE"
php /var/www/html/maintenance/run.php dumpBackup.php --full --output=file:$OUTPUT_FILE

if [ -f "$OUTPUT_FILE" ]; then
echo "Export successful!"
echo "File saved to: $OUTPUT_FILE"
echo "On host system: ~/wiki-container/${DATE}_wiki_export.xml"
else
echo "Export failed!"
fi
EXPORT_EOF
chmod +x /var/www/html/export_wiki.sh

cat > /var/www/html/import_wiki.sh << 'IMPORT_EOF'
#!/bin/bash
echo "=== Wiki Import Tool ==="
echo ""
echo "Available XML files in /export:"
ls -la /export/*.xml 2>/dev/null || echo "No XML files found"
echo ""

if [ -z "$1" ]; then
echo "Usage: /var/www/html/import_wiki.sh <filename>"
echo "Example: /var/www/html/import_wiki.sh /export/wiki.xml"
exit 1
fi

if [ ! -f "$1" ]; then
echo "Error: File $1 not found!"
exit 1
fi

echo "Importing from: $1"
echo "This may take several minutes..."

php /var/www/html/maintenance/run.php importDump.php "$1"

if [ $? -eq 0 ]; then
echo "Import completed!"
echo "Rebuilding indexes..."
php /var/www/html/maintenance/run.php rebuildrecentchanges.php
php /var/www/html/maintenance/run.php initSiteStats.php
echo "Done!"
else
echo "Import failed! Check /tmp/mediawiki-debug.log for details"
fi
IMPORT_EOF
chmod +x /var/www/html/import_wiki.sh

# Create status check script
cat > /var/www/html/check_status.sh << 'STATUS_EOF'
#!/bin/bash
cd /var/www/html
echo "=== Wiki Status ==="
echo "Pages: $(mysql --user=wikiuser --password=wikipass completenoobs_wiki -e "SELECT COUNT(*) FROM page;" -s -N 2>/dev/null || echo "Error")"
echo "Users: $(mysql --user=wikiuser --password=wikipass completenoobs_wiki -e "SELECT COUNT(*) FROM user WHERE user_id > 0;" -s -N 2>/dev/null || echo "Error")"
echo ""
echo "=== Extensions ==="
if [ -d "extensions/PageNotice" ]; then
echo "PageNotice: Installed ✓"
else
echo "PageNotice: Not installed ✗"
fi
if [ -d "extensions/YouTube" ]; then
echo "YouTube: Installed ✓"
else
echo "YouTube: Not installed ✗"
fi
if [ -d "extensions/SyntaxHighlight_GeSHi" ]; then
echo "SyntaxHighlight: Installed ✓"
else
echo "SyntaxHighlight: Not installed ✗"
fi
echo ""
echo "=== Shared Directory ==="
if [ -d "/export" ]; then
echo "/export mounted ✓"
echo "Files in /export:"
ls -la /export/*.xml 2>/dev/null || echo " No XML files"
else
echo "/export not mounted ✗"
fi
STATUS_EOF
chmod +x /var/www/html/check_status.sh

echo ""
echo "Setup completed!"
echo "Admin: admin / AdminPass123!"

service mariadb stop
</syntaxhighlight>

=== 2.3: Entrypoint Script ===
<syntaxhighlight lang="bash">
nano entrypoint.sh
</syntaxhighlight>

<syntaxhighlight lang="bash">
#!/bin/bash

echo "Starting CompleteNoobs Wiki..."

service mariadb start

# Wait for MariaDB
for i in {1..30}; do
if mysql -e "SELECT 1;" &>/dev/null; then
echo "MariaDB ready!"
break
fi
sleep 1
done

echo ""
echo "========================================="
echo "CompleteNoobs Wiki v0.2 Ready!"
echo "========================================="
echo ""
echo "Access: http://localhost:8080"
echo "Admin: admin / AdminPass123!"
echo ""
echo "Features:"
echo "- MediaWiki 1.44"
echo "- PageNotice extension"
echo "- YouTube extension"
echo "- SyntaxHighlight extension"
echo "- Import/Export via ~/wiki-container"
echo ""
echo "Available commands:"
echo "- Export wiki: docker exec completenoobs_wiki /var/www/html/export_wiki.sh"
echo "- Import XML: docker exec completenoobs_wiki /var/www/html/import_wiki.sh /export/filename.xml"
echo "- Check status: docker exec completenoobs_wiki /var/www/html/check_status.sh"
echo ""

apache2-foreground
</syntaxhighlight>

== Step 3: Build and Run ==

=== 3.1: Build the Image ===
<syntaxhighlight lang="bash">
docker build -t completenoobs/wiki:v0.2 .
</syntaxhighlight>

=== 3.2: Run the Container with Shared Directory ===
<syntaxhighlight lang="bash">
docker run -d -p 8080:80 \
-v ~/wiki-container:/export \
-v completenoobs_mysql:/var/lib/mysql \
-v completenoobs_images:/var/www/html/images \
--name completenoobs_wiki \
completenoobs/wiki:v0.2
</syntaxhighlight>

== Step 4: Import/Export Operations ==

=== 4.1: Import an XML File ===
* https://xml.completenoobs.com/xmlDumps/
==== Place XML file in shared directory ====
<syntaxhighlight lang="bash">
# Copy your XML file to the shared directory
cp ~/Downloads/completenoobs.xml ~/wiki-container/
</syntaxhighlight>

==== Import the file ====
* All files in host <code>wiki-container</code> directory will also be in the containers <code>/export/</code> directory.
<syntaxhighlight lang="bash">
# Run the import command
docker exec completenoobs_wiki /var/www/html/import_wiki.sh /export/completenoobs.xml
</syntaxhighlight>

{{:Restore_the_completenoobs_Main_Page}}

=== 4.2: Export Your Wiki ===
<syntaxhighlight lang="bash">
# Export wiki to dated XML file
docker exec completenoobs_wiki /var/www/html/export_wiki.sh

# Check the exported file
ls -la ~/wiki-container/
</syntaxhighlight>

=== 4.3: Manual Import/Export (Advanced) ===

==== Access container shell ====
<syntaxhighlight lang="bash">
docker exec -it completenoobs_wiki bash
</syntaxhighlight>

==== Manual export with custom filename ====
<syntaxhighlight lang="bash">
php /var/www/html/maintenance/run.php dumpBackup.php --full --output=file:/export/my_wiki_backup.xml
exit
</syntaxhighlight>

==== Manual import with options ====
<syntaxhighlight lang="bash">
# Basic import
php /var/www/html/maintenance/run.php importDump.php /export/wiki.xml

# Import with image uploads
php /var/www/html/maintenance/run.php importDump.php --uploads /export/wiki.xml

# Then rebuild indexes
php /var/www/html/maintenance/run.php rebuildall.php
exit
</syntaxhighlight>

== Step 5: Testing and Verification ==

=== 5.1: Check Wiki Status ===
<syntaxhighlight lang="bash">
docker exec completenoobs_wiki /var/www/html/check_status.sh
</syntaxhighlight>

=== 5.2: Test Extensions ===
1. Visit http://localhost:8080
2. Login with admin / AdminPass123!
3. Create or edit a page and test:
* YouTube: Add <code><youtube>gBML6zuUpK0</youtube></code>
* SyntaxHighlight: Add <nowiki><syntaxhighlight lang="python">print("Hello")</syntaxhighlight></nowiki>

=== 5.3: View Logs ===
<syntaxhighlight lang="bash">
# Container logs
docker logs completenoobs_wiki

# MediaWiki debug log
docker exec completenoobs_wiki tail -f /tmp/mediawiki-debug.log
</syntaxhighlight>

== Step 6: Common Operations ==

=== 6.1: Change Admin Password ===

==== Via Web Interface ====
1. Login at http://localhost:8080
2. Click username → Preferences
3. Go to Password tab
4. Change password

==== Via Terminal ====
<syntaxhighlight lang="bash">
docker exec -it completenoobs_wiki bash
php /var/www/html/maintenance/run.php changePassword.php --user=admin --password=NEWPASSWORD
exit
</syntaxhighlight>

=== 6.2: Backup Your Wiki ===
<syntaxhighlight lang="bash">
# Create dated backup
docker exec completenoobs_wiki /var/www/html/export_wiki.sh

# Copy to safe location
cp ~/wiki-container/*_wiki_export.xml ~/backups/
</syntaxhighlight>

=== 6.3: Restore from Backup ===
<syntaxhighlight lang="bash">
# Place backup in shared directory
cp ~/backups/20250101_wiki_export.xml ~/wiki-container/

# Import the backup
docker exec completenoobs_wiki /var/www/html/import_wiki.sh /export/20250101_wiki_export.xml
</syntaxhighlight>

=== 6.4: Complete Reset ===
<syntaxhighlight lang="bash">
# Stop and remove container
docker stop completenoobs_wiki
docker rm completenoobs_wiki

# Remove volumes (WARNING: This deletes all data!)
docker volume rm completenoobs_mysql completenoobs_images

# Rebuild and start fresh
docker run -d -p 8080:80 \
-v ~/wiki-container:/export \
-v completenoobs_mysql:/var/lib/mysql \
-v completenoobs_images:/var/www/html/images \
--name completenoobs_wiki \
completenoobs/wiki:v0.2
</syntaxhighlight>

== Troubleshooting ==

=== Permission Issues ===
If you encounter permission errors with the shared directory:
<syntaxhighlight lang="bash">
# Fix permissions on host
chmod 777 ~/wiki-container
</syntaxhighlight>

=== Import Failures ===
If imports fail, check:
* File exists in ~/wiki-container
* File is valid XML format
* Sufficient disk space
* Check debug log: <code>docker exec completenoobs_wiki tail /tmp/mediawiki-debug.log</code>

=== Container Won't Start ===
<syntaxhighlight lang="bash">
# Check logs
docker logs completenoobs_wiki

# Try interactive mode
docker run -it --rm completenoobs/wiki:v0.2 bash
</syntaxhighlight>

== Summary ==
This setup provides:
* Clean MediaWiki 1.44 installation
* Essential extensions (PageNotice, YouTube, SyntaxHighlight)
* Simple import/export via ~/wiki-container directory
* No automatic updates - full control over your content
* Easy backup and restore capabilities

The shared directory approach gives you complete control over when and what to import/export, making it ideal for:
* Migrating content between wikis
* Regular backups
* Sharing wiki content
* Testing imports before applying to production

CompleteNoobs Docker Image Install

2025-09-02T14:36:54Z

AwesomO:

* [[CompleteNoobs_Docker_Image_0.2_Install_Basics| cnoobs-wiki 0.2 basic install guide]]

CompleteNoobs Docker Image 0.2 Install Basics

2025-09-02T14:31:39Z

AwesomO: /* Create directory for file sharing */

* Requires docker installed on system

== Download image==
* Download the completenoobs container image.
<code>docker pull completenoobs/cnoobs-wiki:0.2</code>

== Create directory for file sharing ==
* If you do not create this directory - docker will create one for you when you run the <code>docker run</code> command.
** If docker run creates the directory, you will not have permissions to send data to that directory.
** Change permission's if that happens <code>sudo chmod 777 ~/wiki-container</code>
<code>mkdir ~/wiki-container</code>

== Run image ==

<pre>
docker run -d -p 8080:80 \
-v ~/wiki-container:/export \
-v completenoobs_mysql:/var/lib/mysql \
-v completenoobs_images:/var/www/html/images \
--name completenoobs_wiki \
completenoobs/cnoobs-wiki:0.2
</pre>

== Download XMl ==

* https://xml.completenoobs.com/xmlDumps/
Download an xml file, like:<code>01_09_25.Noobs.xml</code>
* Move to <code>~/wiki-container/</code> directory

== Import XML ==

<code>docker exec completenoobs_wiki /var/www/html/import_wiki.sh /export/01_09_25.Noobs.xml</code>

== Check Wiki ==
* In browser go to this address
<code>http://localhost:8080</code>
<br>
{{:Restore_the_completenoobs_Main_Page}}

==Change Admin Password==

* Can be done with 'Web Browser GUI' or 'Terminal'
* Default Password for user <b>Admin</b> = <code>AdminPass123!</code>
=== Via Web Interface ===
1. Login at http://localhost:8080
2. Click username → Preferences
3. Go to Password tab
4. Change password

=== Via Terminal ===
<syntaxhighlight lang="bash">
docker exec -it completenoobs_wiki bash
php /var/www/html/maintenance/run.php changePassword.php --user=admin --password=NEWPASSWORD
exit
</syntaxhighlight>

==Export a backup of your wiki==
* This will create a backup of your wiki to a dated.xml file <code>20250902_wiki_export.xml</code>, which you can find in your <code>~/wiki-container</code> directory on host, or <code>/export/</code> directory in container.
<code>docker exec completenoobs_wiki /var/www/html/export_wiki.sh</code>

==Remove container==

To completely remove the <code>completenoobs/cnoobs-wiki:0.1</code> container and image from your Ubuntu 24.04 system, follow these steps. <br>
You can also remove associated persistent storage volumes if they were created.<br><br>

<b>Step 1: Stop and Remove the Container</b><br>
If the container is running, stop it and then remove it.<br>
<syntaxhighlight lang="bash">
docker stop completenoobs_wiki
docker rm completenoobs_wiki
</syntaxhighlight>
Alternatively, stop and remove in one command:<br>
<syntaxhighlight lang="bash">
docker rm -f completenoobs_wiki
</syntaxhighlight><br>

<b>Step 2: Remove the Docker Image</b><br>
Remove the <code>completenoobs/cnoobs-wiki:0.2</code> image.<br>
<syntaxhighlight lang="bash">
docker rmi completenoobs/cnoobs-wiki:0.2
</syntaxhighlight>
Note: If the image is in use by other containers, remove those containers first or use <code>docker rmi -f completenoobs/cnoobs-wiki:0.1</code> to force removal (use with caution).<br><br>

<b>Step 3: Remove Persistent Storage Volumes (Optional)</b><br>
If you used persistent storage, remove the associated volumes to free up space.<br>
<syntaxhighlight lang="bash">
docker volume rm completenoobs_mysql completenoobs_images
</syntaxhighlight>
Note: Ensure no other containers are using these volumes, as this will delete all stored data.<br><br>

<b>Step 4: Verify Removal</b><br>
Check that the container, image, and volumes are removed.<br>
- List all containers (including stopped ones):<br>
<syntaxhighlight lang="bash">
docker ps -a
</syntaxhighlight>
- List all images:<br>
<syntaxhighlight lang="bash">
docker images
</syntaxhighlight>
- List all volumes:<br>
<syntaxhighlight lang="bash">
docker volume ls
</syntaxhighlight>
If any items remain, repeat the relevant removal commands or check for dependencies.

CompleteNoobs Docker Image 0.2 Install Basics

2025-09-02T14:31:06Z

AwesomO: Created page with " * Requires docker installed on system == Download image== * Download the completenoobs container image. <code>docker pull completenoobs/cnoobs-wiki:0.2</code> == Create directory for file sharing == * If you do not create this file - docker will create one for you when you run the <code>docker run</code> command. ** If docker run creates the file, you will not have permissions to send data to that directory. ** Change permission's if that happens <code>sudo chmod 777..."

* Requires docker installed on system

== Download image==
* Download the completenoobs container image.
<code>docker pull completenoobs/cnoobs-wiki:0.2</code>

== Create directory for file sharing ==
* If you do not create this file - docker will create one for you when you run the <code>docker run</code> command.
** If docker run creates the file, you will not have permissions to send data to that directory.
** Change permission's if that happens <code>sudo chmod 777 ~/wiki-container</code>
<code>mkdir ~/wiki-container</code>

== Run image ==

<pre>
docker run -d -p 8080:80 \
-v ~/wiki-container:/export \
-v completenoobs_mysql:/var/lib/mysql \
-v completenoobs_images:/var/www/html/images \
--name completenoobs_wiki \
completenoobs/cnoobs-wiki:0.2
</pre>

== Download XMl ==

* https://xml.completenoobs.com/xmlDumps/
Download an xml file, like:<code>01_09_25.Noobs.xml</code>
* Move to <code>~/wiki-container/</code> directory

== Import XML ==

<code>docker exec completenoobs_wiki /var/www/html/import_wiki.sh /export/01_09_25.Noobs.xml</code>

== Check Wiki ==
* In browser go to this address
<code>http://localhost:8080</code>
<br>
{{:Restore_the_completenoobs_Main_Page}}

==Change Admin Password==

* Can be done with 'Web Browser GUI' or 'Terminal'
* Default Password for user <b>Admin</b> = <code>AdminPass123!</code>
=== Via Web Interface ===
1. Login at http://localhost:8080
2. Click username → Preferences
3. Go to Password tab
4. Change password

=== Via Terminal ===
<syntaxhighlight lang="bash">
docker exec -it completenoobs_wiki bash
php /var/www/html/maintenance/run.php changePassword.php --user=admin --password=NEWPASSWORD
exit
</syntaxhighlight>

==Export a backup of your wiki==
* This will create a backup of your wiki to a dated.xml file <code>20250902_wiki_export.xml</code>, which you can find in your <code>~/wiki-container</code> directory on host, or <code>/export/</code> directory in container.
<code>docker exec completenoobs_wiki /var/www/html/export_wiki.sh</code>

==Remove container==

To completely remove the <code>completenoobs/cnoobs-wiki:0.1</code> container and image from your Ubuntu 24.04 system, follow these steps. <br>
You can also remove associated persistent storage volumes if they were created.<br><br>

<b>Step 1: Stop and Remove the Container</b><br>
If the container is running, stop it and then remove it.<br>
<syntaxhighlight lang="bash">
docker stop completenoobs_wiki
docker rm completenoobs_wiki
</syntaxhighlight>
Alternatively, stop and remove in one command:<br>
<syntaxhighlight lang="bash">
docker rm -f completenoobs_wiki
</syntaxhighlight><br>

<b>Step 2: Remove the Docker Image</b><br>
Remove the <code>completenoobs/cnoobs-wiki:0.2</code> image.<br>
<syntaxhighlight lang="bash">
docker rmi completenoobs/cnoobs-wiki:0.2
</syntaxhighlight>
Note: If the image is in use by other containers, remove those containers first or use <code>docker rmi -f completenoobs/cnoobs-wiki:0.1</code> to force removal (use with caution).<br><br>

<b>Step 3: Remove Persistent Storage Volumes (Optional)</b><br>
If you used persistent storage, remove the associated volumes to free up space.<br>
<syntaxhighlight lang="bash">
docker volume rm completenoobs_mysql completenoobs_images
</syntaxhighlight>
Note: Ensure no other containers are using these volumes, as this will delete all stored data.<br><br>

<b>Step 4: Verify Removal</b><br>
Check that the container, image, and volumes are removed.<br>
- List all containers (including stopped ones):<br>
<syntaxhighlight lang="bash">
docker ps -a
</syntaxhighlight>
- List all images:<br>
<syntaxhighlight lang="bash">
docker images
</syntaxhighlight>
- List all volumes:<br>
<syntaxhighlight lang="bash">
docker volume ls
</syntaxhighlight>
If any items remain, repeat the relevant removal commands or check for dependencies.

CompleteNoobs Docker Image Install

2025-09-02T12:27:21Z

AwesomO: Created page with "placeholder"

placeholder

CompleteNoobs Docker Image 2

2025-09-02T12:24:39Z

AwesomO: Created page with " ==todo== * Use Dir for import export of xml. * Min scripts - just setup mediawiki with extensions. = Complete Noobs Docker Wiki Tutorial v0.2 = * Version 0.2 - Simplified with manual import/export * Docker install guide == Overview == This tutorial creates a MediaWiki Docker container with: * MediaWiki 1.44 * PageNotice extension (for license notices) * YouTube extension (for video embedding) * Shared directory for XML import/export == Prere..."

==todo==
* Use Dir for import export of xml.
* Min scripts - just setup mediawiki with extensions.

= Complete Noobs Docker Wiki Tutorial v0.2 =
* Version 0.2 - Simplified with manual import/export
* [[Docker_Install_Guide| Docker install guide]]

== Overview ==
This tutorial creates a MediaWiki Docker container with:
* MediaWiki 1.44
* PageNotice extension (for license notices)
* YouTube extension (for video embedding)
* Shared directory for XML import/export

== Prerequisites ==
* Ubuntu 24.04
* Docker installed and running
* Your user in docker group: <code>sudo usermod -aG docker $USER</code> (then logout/login)

== Step 1: Create Directory Structure ==

=== 1.1: Create Project Directory ===
<syntaxhighlight lang="bash">
mkdir ~/completenoobs-docker-v2
cd ~/completenoobs-docker-v2
</syntaxhighlight>

=== 1.2: Create Shared Directory ===
<syntaxhighlight lang="bash">
mkdir ~/wiki-container
</syntaxhighlight>
This directory will be used for importing and exporting XML files.

== Step 2: Create All Files ==

=== 2.1: Dockerfile ===
<syntaxhighlight lang="bash">
nano Dockerfile
</syntaxhighlight>

<syntaxhighlight lang="dockerfile">
FROM mediawiki:1.44

# Install dependencies
RUN apt-get update && apt-get install -y \
mariadb-server \
python3-pygments \
curl \
wget \
unzip \
nano \
vim \
git \
&& apt-get clean

# Copy setup script
COPY setup_wiki.sh /usr/src/setup_wiki.sh
COPY entrypoint.sh /entrypoint.sh

# Make executable
RUN chmod +x /usr/src/setup_wiki.sh /entrypoint.sh

# Setup wiki
RUN /usr/src/setup_wiki.sh

EXPOSE 80
VOLUME /var/lib/mysql
VOLUME /var/www/html/images
VOLUME /export

ENTRYPOINT ["/entrypoint.sh"]
</syntaxhighlight>

=== 2.2: Main Setup Script ===
<syntaxhighlight lang="bash">
nano setup_wiki.sh
</syntaxhighlight>

<syntaxhighlight lang="bash">
#!/bin/bash
set -e

echo "Setting up CompleteNoobs Wiki..."

# Initialize MariaDB
if [ ! -d "/var/lib/mysql/mysql" ]; then
mysql_install_db --user=mysql --datadir=/var/lib/mysql
fi

service mariadb start

# Wait for MariaDB
for i in {1..30}; do
if mysql -e "SELECT 1;" &>/dev/null; then
echo "MariaDB ready!"
break
fi
sleep 2
done

# Setup database
mysql -e "CREATE DATABASE IF NOT EXISTS completenoobs_wiki CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
mysql -e "CREATE USER IF NOT EXISTS 'wikiuser'@'127.0.0.1' IDENTIFIED BY 'wikipass';"
mysql -e "GRANT ALL PRIVILEGES ON completenoobs_wiki.* TO 'wikiuser'@'127.0.0.1';"
mysql -e "CREATE USER IF NOT EXISTS 'wikiuser'@'localhost' IDENTIFIED BY 'wikipass';"
mysql -e "GRANT ALL PRIVILEGES ON completenoobs_wiki.* TO 'wikiuser'@'localhost';"
mysql -e "FLUSH PRIVILEGES;"

# Install MediaWiki
cd /var/www/html
php maintenance/install.php \
--dbtype=mysql \
--dbserver=127.0.0.1 \
--dbname=completenoobs_wiki \
--dbuser=wikiuser \
--dbpass=wikipass \
--server="http://localhost:8080" \
--scriptpath="" \
--lang=en \
--pass=AdminPass123! \
"CompleteNoobs Wiki" \
"admin"

# Download and install extensions
cd extensions/
echo "Installing PageNotice extension..."
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/PageNotice --branch REL1_44 || echo "PageNotice download failed, continuing..."

echo "Installing YouTube extension..."
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/YouTube --branch REL1_44 || echo "YouTube download failed, continuing..."

cd /var/www/html

# Configure LocalSettings.php
cat >> LocalSettings.php << 'EOF'

# Basic settings
$wgEnableUploads = true;
$wgUseImageMagick = true;
$wgImageMagickConvertCommand = "/usr/bin/convert";
$wgDefaultSkin = "vector-2022";
$wgAllowExternalImages = true;

# Debug settings (remove in production)
$wgShowExceptionDetails = true;
$wgDebugLogFile = "/tmp/mediawiki-debug.log";

# PageNotice extension
if ( file_exists( "$IP/extensions/PageNotice/extension.json" ) ) {
wfLoadExtension( 'PageNotice' );
}

# YouTube extension
if ( file_exists( "$IP/extensions/YouTube/extension.json" ) ) {
wfLoadExtension( 'YouTube' );
}

# SyntaxHighlight (usually bundled)
if ( file_exists( "$IP/extensions/SyntaxHighlight_GeSHi/extension.json" ) ) {
wfLoadExtension( 'SyntaxHighlight_GeSHi' );
$wgPygmentizePath = '/usr/bin/pygmentize';
}
EOF

# Create helper scripts
cat > /var/www/html/export_wiki.sh << 'EXPORT_EOF'
#!/bin/bash
echo "=== Wiki Export Tool ==="
DATE=$(date +%Y%m%d)
OUTPUT_FILE="/export/${DATE}_wiki_export.xml"

echo "Exporting wiki to: $OUTPUT_FILE"
php /var/www/html/maintenance/run.php dumpBackup.php --full --output=file:$OUTPUT_FILE

if [ -f "$OUTPUT_FILE" ]; then
echo "Export successful!"
echo "File saved to: $OUTPUT_FILE"
echo "On host system: ~/wiki-container/${DATE}_wiki_export.xml"
else
echo "Export failed!"
fi
EXPORT_EOF
chmod +x /var/www/html/export_wiki.sh

cat > /var/www/html/import_wiki.sh << 'IMPORT_EOF'
#!/bin/bash
echo "=== Wiki Import Tool ==="
echo ""
echo "Available XML files in /export:"
ls -la /export/*.xml 2>/dev/null || echo "No XML files found"
echo ""

if [ -z "$1" ]; then
echo "Usage: /var/www/html/import_wiki.sh <filename>"
echo "Example: /var/www/html/import_wiki.sh /export/wiki.xml"
exit 1
fi

if [ ! -f "$1" ]; then
echo "Error: File $1 not found!"
exit 1
fi

echo "Importing from: $1"
echo "This may take several minutes..."

php /var/www/html/maintenance/run.php importDump.php "$1"

if [ $? -eq 0 ]; then
echo "Import completed!"
echo "Rebuilding indexes..."
php /var/www/html/maintenance/run.php rebuildrecentchanges.php
php /var/www/html/maintenance/run.php initSiteStats.php
echo "Done!"
else
echo "Import failed! Check /tmp/mediawiki-debug.log for details"
fi
IMPORT_EOF
chmod +x /var/www/html/import_wiki.sh

# Create status check script
cat > /var/www/html/check_status.sh << 'STATUS_EOF'
#!/bin/bash
cd /var/www/html
echo "=== Wiki Status ==="
echo "Pages: $(mysql --user=wikiuser --password=wikipass completenoobs_wiki -e "SELECT COUNT(*) FROM page;" -s -N 2>/dev/null || echo "Error")"
echo "Users: $(mysql --user=wikiuser --password=wikipass completenoobs_wiki -e "SELECT COUNT(*) FROM user WHERE user_id > 0;" -s -N 2>/dev/null || echo "Error")"
echo ""
echo "=== Extensions ==="
if [ -d "extensions/PageNotice" ]; then
echo "PageNotice: Installed ✓"
else
echo "PageNotice: Not installed ✗"
fi
if [ -d "extensions/YouTube" ]; then
echo "YouTube: Installed ✓"
else
echo "YouTube: Not installed ✗"
fi
if [ -d "extensions/SyntaxHighlight_GeSHi" ]; then
echo "SyntaxHighlight: Installed ✓"
else
echo "SyntaxHighlight: Not installed ✗"
fi
echo ""
echo "=== Shared Directory ==="
if [ -d "/export" ]; then
echo "/export mounted ✓"
echo "Files in /export:"
ls -la /export/*.xml 2>/dev/null || echo " No XML files"
else
echo "/export not mounted ✗"
fi
STATUS_EOF
chmod +x /var/www/html/check_status.sh

echo ""
echo "Setup completed!"
echo "Admin: admin / AdminPass123!"

service mariadb stop
</syntaxhighlight>

=== 2.3: Entrypoint Script ===
<syntaxhighlight lang="bash">
nano entrypoint.sh
</syntaxhighlight>

<syntaxhighlight lang="bash">
#!/bin/bash

echo "Starting CompleteNoobs Wiki..."

service mariadb start

# Wait for MariaDB
for i in {1..30}; do
if mysql -e "SELECT 1;" &>/dev/null; then
echo "MariaDB ready!"
break
fi
sleep 1
done

echo ""
echo "========================================="
echo "CompleteNoobs Wiki v0.2 Ready!"
echo "========================================="
echo ""
echo "Access: http://localhost:8080"
echo "Admin: admin / AdminPass123!"
echo ""
echo "Features:"
echo "- MediaWiki 1.44"
echo "- PageNotice extension"
echo "- YouTube extension"
echo "- SyntaxHighlight extension"
echo "- Import/Export via ~/wiki-container"
echo ""
echo "Available commands:"
echo "- Export wiki: docker exec completenoobs_wiki /var/www/html/export_wiki.sh"
echo "- Import XML: docker exec completenoobs_wiki /var/www/html/import_wiki.sh /export/filename.xml"
echo "- Check status: docker exec completenoobs_wiki /var/www/html/check_status.sh"
echo ""

apache2-foreground
</syntaxhighlight>

== Step 3: Build and Run ==

=== 3.1: Build the Image ===
<syntaxhighlight lang="bash">
docker build -t completenoobs/wiki:v0.2 .
</syntaxhighlight>

=== 3.2: Run the Container with Shared Directory ===
<syntaxhighlight lang="bash">
docker run -d -p 8080:80 \
-v ~/wiki-container:/export \
-v completenoobs_mysql:/var/lib/mysql \
-v completenoobs_images:/var/www/html/images \
--name completenoobs_wiki \
completenoobs/wiki:v0.2
</syntaxhighlight>

== Step 4: Import/Export Operations ==

=== 4.1: Import an XML File ===
* https://xml.completenoobs.com/xmlDumps/
==== Place XML file in shared directory ====
<syntaxhighlight lang="bash">
# Copy your XML file to the shared directory
cp ~/Downloads/completenoobs.xml ~/wiki-container/
</syntaxhighlight>

==== Import the file ====
* All files in host <code>wiki-container</code> directory will also be in the containers <code>/export/</code> directory.
<syntaxhighlight lang="bash">
# Run the import command
docker exec completenoobs_wiki /var/www/html/import_wiki.sh /export/completenoobs.xml
</syntaxhighlight>

{{:Restore_the_completenoobs_Main_Page}}

=== 4.2: Export Your Wiki ===
<syntaxhighlight lang="bash">
# Export wiki to dated XML file
docker exec completenoobs_wiki /var/www/html/export_wiki.sh

# Check the exported file
ls -la ~/wiki-container/
</syntaxhighlight>

=== 4.3: Manual Import/Export (Advanced) ===

==== Access container shell ====
<syntaxhighlight lang="bash">
docker exec -it completenoobs_wiki bash
</syntaxhighlight>

==== Manual export with custom filename ====
<syntaxhighlight lang="bash">
php /var/www/html/maintenance/run.php dumpBackup.php --full --output=file:/export/my_wiki_backup.xml
exit
</syntaxhighlight>

==== Manual import with options ====
<syntaxhighlight lang="bash">
# Basic import
php /var/www/html/maintenance/run.php importDump.php /export/wiki.xml

# Import with image uploads
php /var/www/html/maintenance/run.php importDump.php --uploads /export/wiki.xml

# Then rebuild indexes
php /var/www/html/maintenance/run.php rebuildall.php
exit
</syntaxhighlight>

== Step 5: Testing and Verification ==

=== 5.1: Check Wiki Status ===
<syntaxhighlight lang="bash">
docker exec completenoobs_wiki /var/www/html/check_status.sh
</syntaxhighlight>

=== 5.2: Test Extensions ===
1. Visit http://localhost:8080
2. Login with admin / AdminPass123!
3. Create or edit a page and test:
* YouTube: Add <code><youtube>VIDEO_ID</youtube></code>
* SyntaxHighlight: Add <nowiki><syntaxhighlight lang="python">print("Hello")</syntaxhighlight></nowiki>

=== 5.3: View Logs ===
<syntaxhighlight lang="bash">
# Container logs
docker logs completenoobs_wiki

# MediaWiki debug log
docker exec completenoobs_wiki tail -f /tmp/mediawiki-debug.log
</syntaxhighlight>

== Step 6: Common Operations ==

=== 6.1: Change Admin Password ===

==== Via Web Interface ====
1. Login at http://localhost:8080
2. Click username → Preferences
3. Go to Password tab
4. Change password

==== Via Terminal ====
<syntaxhighlight lang="bash">
docker exec -it completenoobs_wiki bash
php /var/www/html/maintenance/run.php changePassword.php --user=admin --password=NEWPASSWORD
exit
</syntaxhighlight>

=== 6.2: Backup Your Wiki ===
<syntaxhighlight lang="bash">
# Create dated backup
docker exec completenoobs_wiki /var/www/html/export_wiki.sh

# Copy to safe location
cp ~/wiki-container/*_wiki_export.xml ~/backups/
</syntaxhighlight>

=== 6.3: Restore from Backup ===
<syntaxhighlight lang="bash">
# Place backup in shared directory
cp ~/backups/20250101_wiki_export.xml ~/wiki-container/

# Import the backup
docker exec completenoobs_wiki /var/www/html/import_wiki.sh /export/20250101_wiki_export.xml
</syntaxhighlight>

=== 6.4: Complete Reset ===
<syntaxhighlight lang="bash">
# Stop and remove container
docker stop completenoobs_wiki
docker rm completenoobs_wiki

# Remove volumes (WARNING: This deletes all data!)
docker volume rm completenoobs_mysql completenoobs_images

# Rebuild and start fresh
docker run -d -p 8080:80 \
-v ~/wiki-container:/export \
-v completenoobs_mysql:/var/lib/mysql \
-v completenoobs_images:/var/www/html/images \
--name completenoobs_wiki \
completenoobs/wiki:v0.2
</syntaxhighlight>

== Troubleshooting ==

=== Permission Issues ===
If you encounter permission errors with the shared directory:
<syntaxhighlight lang="bash">
# Fix permissions on host
chmod 777 ~/wiki-container
</syntaxhighlight>

=== Import Failures ===
If imports fail, check:
* File exists in ~/wiki-container
* File is valid XML format
* Sufficient disk space
* Check debug log: <code>docker exec completenoobs_wiki tail /tmp/mediawiki-debug.log</code>

=== Container Won't Start ===
<syntaxhighlight lang="bash">
# Check logs
docker logs completenoobs_wiki

# Try interactive mode
docker run -it --rm completenoobs/wiki:v0.2 bash
</syntaxhighlight>

== Summary ==
This setup provides:
* Clean MediaWiki 1.44 installation
* Essential extensions (PageNotice, YouTube, SyntaxHighlight)
* Simple import/export via ~/wiki-container directory
* No automatic updates - full control over your content
* Easy backup and restore capabilities

The shared directory approach gives you complete control over when and what to import/export, making it ideal for:
* Migrating content between wikis
* Regular backups
* Sharing wiki content
* Testing imports before applying to production

CompleteNoobs Docker Image Creation

2025-09-02T10:53:40Z

AwesomO: /* Complete Noobs Docker Wiki Tutorial */

= Versions =
* This is version 0.1 - many bugs
* [[todo| CompleteNoobs Docker Image 0.2]]

= Complete Noobs Docker Wiki Tutorial =
* [[Docker_Install_Guide| Docker install guide]]
==errors==
* This mainly works - just need to fix the extensions popular pages and contrubtion scores
* The XML updater requires more work - currently idea placeholder

== Prerequisites ==
* Ubuntu 24.04
* Docker installed and running
* Your user in docker group: <code>sudo usermod -aG docker $USER</code> (then logout/login)

== Step 2: Create All Files ==

=== 2.1: Dockerfile ===
<syntaxhighlight lang="bash">
nano Dockerfile
</syntaxhighlight>
Copy this exactly:

<syntaxhighlight lang="dockerfile">
FROM mediawiki:1.44
# Mediawiki 1.44 used over latest because can confirm extensions youtube and pagenotice works
# Install dependencies
RUN apt-get update && apt-get install -y \
mariadb-server \
python3 \
python3-requests \
python3-bs4 \
python3-pygments \
curl \
wget \
unzip \
nano \
git \
&& apt-get clean

# Copy scripts
COPY download_latest_xml.py /usr/src/download_latest_xml.py
COPY setup_wiki.sh /usr/src/setup_wiki.sh
COPY update_xml.sh /usr/src/update_xml.sh
COPY entrypoint.sh /entrypoint.sh

# Make executable
RUN chmod +x /usr/src/setup_wiki.sh /entrypoint.sh /usr/src/update_xml.sh

# Download XML
RUN python3 /usr/src/download_latest_xml.py

# Setup wiki
RUN /usr/src/setup_wiki.sh

EXPOSE 80
VOLUME /var/lib/mysql
VOLUME /var/www/html/images

ENTRYPOINT ["/entrypoint.sh"]
</syntaxhighlight>

=== 2.2: XML Download Script ===
<syntaxhighlight lang="bash">
nano download_latest_xml.py
</syntaxhighlight>

<syntaxhighlight lang="python">
#!/usr/bin/env python3
import os
import requests
from bs4 import BeautifulSoup
import re

BASE_URL = "https://xml.completenoobs.com/xmlDumps/"

def parse_date_from_dump(dump_name):
match = re.match(r'(\d{2})_(\d{2})_(\d{2})\.Noobs', dump_name)
if match:
day, month, year = match.groups()
year_int = int(year)
full_year = 2000 + year_int if year_int <= 49 else 1900 + year_int
return (full_year, int(month), int(day))
return (0, 0, 0)

def get_available_dumps():
try:
response = requests.get(BASE_URL, timeout=30)
response.raise_for_status()
soup = BeautifulSoup(response.text, 'html.parser')
dumps = [link.get('href').rstrip('/') for link in soup.find_all('a')
if re.match(r'\d{2}_\d{2}_\d{2}\.Noobs/$', link.get('href', ''))]
return sorted(dumps, key=parse_date_from_dump, reverse=True)
except Exception as e:
print(f"Error fetching dumps: {e}")
return []

def get_dump_files(dump):
try:
response = requests.get(f"{BASE_URL}{dump}/", timeout=30)
response.raise_for_status()
soup = BeautifulSoup(response.text, 'html.parser')
files = [link.get('href') for link in soup.find_all('a')
if link.get('href', '').endswith('.xml')]
return sorted(files, reverse=True)
except Exception as e:
print(f"Error fetching dump files: {e}")
return []

def download_file(url, filename):
try:
print(f"Downloading {filename}...")
response = requests.get(url, stream=True, timeout=60)
response.raise_for_status()

total_size = int(response.headers.get('content-length', 0))
downloaded = 0

with open(filename, 'wb') as f:
for chunk in response.iter_content(chunk_size=8192):
if chunk:
f.write(chunk)
downloaded += len(chunk)
if total_size > 0:
progress = (downloaded / total_size) * 100
print(f"\rProgress: {progress:.1f}%", end='', flush=True)
print()
return True
except Exception as e:
print(f"Error downloading {filename}: {e}")
return False

def main():
print("Fetching available XML dumps...")
dumps = get_available_dumps()

if not dumps:
print("No dumps found!")
exit(1)

newest_dump = dumps[0]
print(f"Latest dump: {newest_dump}")

files = get_dump_files(newest_dump)
if not files:
print("No XML files found in latest dump!")
exit(1)

newest_xml = files[0]
xml_url = f"{BASE_URL}{newest_dump}/{newest_xml}"
local_filename = "/tmp/completenoobs_dump.xml"

if download_file(xml_url, local_filename):
print(f"Successfully downloaded {newest_xml}")
with open("/tmp/dump_info.txt", "w") as f:
f.write(f"{newest_dump}/{newest_xml}")
else:
print("Failed to download XML dump!")
exit(1)

if __name__ == "__main__":
main()
</syntaxhighlight>

=== 2.3: Main Setup Script ===
<syntaxhighlight lang="bash">
nano setup_wiki.sh
</syntaxhighlight>

<syntaxhighlight lang="bash">
#!/bin/bash
set -e

echo "Setting up CompleteNoobs Wiki..."

# Initialize MariaDB
if [ ! -d "/var/lib/mysql/mysql" ]; then
mysql_install_db --user=mysql --datadir=/var/lib/mysql
fi

service mariadb start

# Wait for MariaDB
for i in {1..30}; do
if mysql -e "SELECT 1;" &>/dev/null; then
echo "MariaDB ready!"
break
fi
sleep 2
done

# Setup database
mysql -e "CREATE DATABASE IF NOT EXISTS completenoobs_wiki CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
mysql -e "CREATE USER IF NOT EXISTS 'wikiuser'@'127.0.0.1' IDENTIFIED BY 'wikipass';"
mysql -e "GRANT ALL PRIVILEGES ON completenoobs_wiki.* TO 'wikiuser'@'127.0.0.1';"
mysql -e "CREATE USER IF NOT EXISTS 'wikiuser'@'localhost' IDENTIFIED BY 'wikipass';"
mysql -e "GRANT ALL PRIVILEGES ON completenoobs_wiki.* TO 'wikiuser'@'localhost';"
mysql -e "FLUSH PRIVILEGES;"

# Install MediaWiki
cd /var/www/html
php maintenance/install.php \
--dbtype=mysql \
--dbserver=127.0.0.1 \
--dbname=completenoobs_wiki \
--dbuser=wikiuser \
--dbpass=wikipass \
--server="http://localhost:8080" \
--scriptpath="" \
--lang=en \
--pass=AdminPass123! \
"CompleteNoobs Wiki" \
"admin"

# Download and install extensions
cd extensions/
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/PageNotice --branch REL1_44 || echo "PageNotice download failed, continuing..."
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/YouTube --branch REL1_44 || echo "YouTube download failed, continuing..."
cd /var/www/html

# Configure LocalSettings.php
cat >> LocalSettings.php << 'EOF'
# Basic settings
$wgEnableUploads = true;
$wgUseImageMagick = true;
$wgImageMagickConvertCommand = "/usr/bin/convert";
$wgDefaultSkin = "vector-2022";
$wgAllowExternalImages = true;

# Debug (can be removed later)
$wgShowExceptionDetails = true;
$wgDebugLogFile = "/tmp/mediawiki-debug.log";

# PageNotice extension (if available)
if ( file_exists( "$IP/extensions/PageNotice/extension.json" ) ) {
wfLoadExtension( 'PageNotice' );
}

# YouTube extension (if available)
if ( file_exists( "$IP/extensions/YouTube/extension.json" ) ) {
wfLoadExtension( 'YouTube' );
}

# SyntaxHighlight (usually bundled)
if ( file_exists( "$IP/extensions/SyntaxHighlight_GeSHi/extension.json" ) ) {
wfLoadExtension( 'SyntaxHighlight_GeSHi' );
$wgPygmentizePath = '/usr/bin/pygmentize';
}
EOF

# Import XML dump if available
if [ -f "/tmp/completenoobs_dump.xml" ]; then
echo "Importing XML dump..."

if php maintenance/importDump.php --uploads < /tmp/completenoobs_dump.xml; then
echo "XML import completed!"
else
echo "XML import had warnings"
fi

# Basic maintenance
php maintenance/update.php --quick || echo "Update completed with warnings"
php maintenance/rebuildrecentchanges.php || echo "RecentChanges rebuilt with warnings"
php maintenance/initSiteStats.php || echo "SiteStats initialized with warnings"

if [ -f "/tmp/dump_info.txt" ]; then
echo "Import: $(cat /tmp/dump_info.txt)" > /var/www/html/.last_import
echo "Date: $(date)" >> /var/www/html/.last_import
fi
else
echo "No XML dump found - starting with empty wiki"
fi

# Copy update script to accessible location
cp /usr/src/update_xml.sh /var/www/html/update_xml.sh
chmod +x /var/www/html/update_xml.sh

# Create user-friendly update wrapper
cat > /var/www/html/check_updates.sh << 'UPDATE_WRAPPER_EOF'
#!/bin/bash
echo "=== CompleteNoobs Wiki Update Checker ==="
echo ""
echo "This tool checks for new content from the CompleteNoobs XML repository"
echo "and imports ONLY new pages, preserving all your local edits."
echo ""

/var/www/html/update_xml.sh
UPDATE_WRAPPER_EOF
chmod +x /var/www/html/check_updates.sh

# Create simple status script
cat > /var/www/html/check_status.sh << 'STATUS_EOF'
#!/bin/bash
cd /var/www/html
echo "=== Wiki Status ==="
echo "Pages: $(mysql --user=wikiuser --password=wikipass completenoobs_wiki -e "SELECT COUNT(*) FROM page;" -s -N 2>/dev/null || echo "Error")"
echo "Users: $(mysql --user=wikiuser --password=wikipass completenoobs_wiki -e "SELECT COUNT(*) FROM user WHERE user_id > 0;" -s -N 2>/dev/null || echo "Error")"
echo ""
echo "=== Extensions ==="
if [ -d "extensions/PageNotice" ]; then
echo "PageNotice: Installed"
else
echo "PageNotice: Not installed"
fi
if [ -d "extensions/YouTube" ]; then
echo "YouTube: Installed"
else
echo "YouTube: Not installed"
fi
if [ -d "extensions/ContributionScores" ]; then
echo "ContributionScores: Installed"
else
echo "ContributionScores: Not installed"
fi
echo ""
echo "=== Update System ==="
if [ -f ".last_import" ]; then
echo "Current version: $(grep 'Import:' .last_import | cut -d' ' -f2)"
echo "Import date: $(grep 'Date:' .last_import | cut -d' ' -f2-)"
else
echo "No version info available"
fi
echo ""
echo "To check for updates: docker exec -it completenoobs_wiki /var/www/html/check_updates.sh"
STATUS_EOF
chmod +x /var/www/html/check_status.sh

echo ""
echo "Setup completed!"
echo "Admin: admin / AdminPass123!"
echo "Update scripts installed:"
echo "- /var/www/html/check_updates.sh (user-friendly)"
echo "- /var/www/html/update_xml.sh (direct)"

# Final counts
PAGES=$(mysql --user=wikiuser --password=wikipass completenoobs_wiki -e "SELECT COUNT(*) FROM page;" -s -N 2>/dev/null || echo "0")
echo "Pages imported: $PAGES"

service mariadb stop
</syntaxhighlight>

=== 2.4: XML Update Script ===
<syntaxhighlight lang="bash">
nano update_xml.sh
</syntaxhighlight>

<syntaxhighlight lang="bash">
#!/bin/bash
set -e

echo "=== CompleteNoobs Wiki XML Updater ==="
echo "This will check for new and updated pages"
echo ""

# Function to check if running in container
check_environment() {
if [ ! -f "/var/www/html/LocalSettings.php" ]; then
echo "Error: This script must be run inside the wiki container"
exit 1
fi
}

# Function to get current XML version
get_current_version() {
if [ -f "/var/www/html/.last_import" ]; then
grep "Import:" /var/www/html/.last_import | cut -d' ' -f2
else
echo "none"
fi
}

# Function to check for updates
check_for_updates() {
python3 - << 'PYTHON_EOF'
import requests
from bs4 import BeautifulSoup
import re
import sys

BASE_URL = "https://xml.completenoobs.com/xmlDumps/"

def parse_date_from_dump(dump_name):
match = re.match(r'(\d{2})_(\d{2})_(\d{2})\.Noobs', dump_name)
if match:
day, month, year = match.groups()
year_int = int(year)
full_year = 2000 + year_int if year_int <= 49 else 1900 + year_int
return (full_year, int(month), int(day))
return (0, 0, 0)

def get_latest_dump():
try:
response = requests.get(BASE_URL, timeout=30)
response.raise_for_status()
soup = BeautifulSoup(response.text, 'html.parser')
dumps = [link.get('href').rstrip('/') for link in soup.find_all('a')
if re.match(r'\d{2}_\d{2}_\d{2}\.Noobs/$', link.get('href', ''))]
if dumps:
latest = sorted(dumps, key=parse_date_from_dump, reverse=True)[0]

# Get XML files from latest dump
response = requests.get(f"{BASE_URL}{latest}/", timeout=30)
response.raise_for_status()
soup = BeautifulSoup(response.text, 'html.parser')
files = [link.get('href') for link in soup.find_all('a')
if link.get('href', '').endswith('.xml')]

if files:
newest_xml = sorted(files, reverse=True)[0]
print(f"{latest}/{newest_xml}")
sys.exit(0)
except Exception as e:
print(f"ERROR: {e}", file=sys.stderr)
sys.exit(1)

print("ERROR: No dumps found", file=sys.stderr)
sys.exit(1)

get_latest_dump()
PYTHON_EOF
}

# Function to download new XML
download_xml() {
local dump_info="$1"
local dump_dir=$(echo "$dump_info" | cut -d'/' -f1)
local xml_file=$(echo "$dump_info" | cut -d'/' -f2)
local url="https://xml.completenoobs.com/xmlDumps/${dump_info}"

echo "Downloading: $xml_file"
echo "From: $dump_dir"
echo "URL: $url"

if wget -O /tmp/new_dump.xml "$url" --progress=bar:force 2>&1; then
echo "Download successful!"
return 0
else
echo "Download failed!"
return 1
fi
}

# Function to backup current database
backup_database() {
echo "Creating database backup..."
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
mysqldump --user=wikiuser --password=wikipass completenoobs_wiki > /tmp/wiki_backup_${TIMESTAMP}.sql
echo "Backup created: /tmp/wiki_backup_${TIMESTAMP}.sql"
}

# Function to analyze and import changes
analyze_and_import() {
echo "Analyzing differences between XML and local wiki..."

# Create analysis and import script for MediaWiki 1.44+
cat > /tmp/analyze_import.php << 'PHP_EOF'
<?php
require_once '/var/www/html/maintenance/Maintenance.php';

class AnalyzeAndImport extends Maintenance {
private $db;
private $new_pages = [];
private $changed_pages = [];
private $unchanged_pages = [];

public function __construct() {
parent::__construct();
$this->addDescription('Analyze and selectively import from XML dump');
}

public function execute() {
$this->db = new mysqli('127.0.0.1', 'wikiuser', 'wikipass', 'completenoobs_wiki');

// MediaWiki 1.35+ uses slots and content tables
// Get existing pages with their content
$query = "
SELECT p.page_title, p.page_id, c.content_address, c.content_sha1
FROM page p
JOIN revision r ON p.page_latest = r.rev_id
JOIN slots s ON r.rev_id = s.slot_revision_id
JOIN slot_roles sr ON s.slot_role_id = sr.role_id
JOIN content c ON s.slot_content_id = c.content_id
WHERE p.page_namespace = 0 AND sr.role_name = 'main'
";

$result = $this->db->query($query);
if (!$result) {
$this->error("Database query failed: " . $this->db->error);
return;
}

$existing = [];
while ($row = $result->fetch_assoc()) {
// Get actual text content
$text_content = $this->getTextContent($row['content_address']);
$existing[$row['page_title']] = [
'id' => $row['page_id'],
'content' => $text_content,
'sha1' => $row['content_sha1']
];
}

// Parse XML and compare
$xml = simplexml_load_file('/tmp/new_dump.xml');

foreach ($xml->page as $page) {
$title = str_replace(' ', '_', (string)$page->title);
$xml_content = (string)$page->revision->text;

if (!isset($existing[$title])) {
// New page
$this->new_pages[$title] = $xml_content;
} else {
// Compare content using SHA1 for efficiency
$xml_sha1 = sha1($xml_content);

if ($existing[$title]['sha1'] !== $xml_sha1) {
// Content is different
$this->changed_pages[$title] = [
'local' => $existing[$title]['content'],
'xml' => $xml_content,
'page_id' => $existing[$title]['id']
];
} else {
$this->unchanged_pages[] = $title;
}
}
}

// Display summary
$this->output("\n=== Update Analysis ===\n");
$this->output("New pages to import: " . count($this->new_pages) . "\n");
$this->output("Changed pages found: " . count($this->changed_pages) . "\n");
$this->output("Unchanged pages: " . count($this->unchanged_pages) . "\n");

// Save analysis for review
file_put_contents('/tmp/update_analysis.json', json_encode([
'new' => array_keys($this->new_pages),
'changed' => array_keys($this->changed_pages),
'unchanged' => $this->unchanged_pages
], JSON_PRETTY_PRINT));

// Show changed pages with preview (limit to first 20 for readability)
if (count($this->changed_pages) > 0) {
$this->output("\n=== Changed Pages ===\n");
$count = 0;
$total_changed = count($this->changed_pages);

foreach ($this->changed_pages as $title => $data) {
$count++;
if ($count <= 20) {
$this->output("\n$count. $title\n");

// Create a simple diff preview (first 300 chars)
$xml_preview = substr($data['xml'], 0, 100);

// Save full diff to file
$safe_title = preg_replace('/[^a-zA-Z0-9_-]/', '_', $title);
$diff_file = "/tmp/diff_${safe_title}.txt";
file_put_contents($diff_file, "=== FULL DIFF FOR: $title ===\n\n");
file_put_contents($diff_file, "--- LOCAL VERSION ---\n", FILE_APPEND);
file_put_contents($diff_file, $data['local'] . "\n\n", FILE_APPEND);
file_put_contents($diff_file, "--- XML VERSION ---\n", FILE_APPEND);
file_put_contents($diff_file, $data['xml'], FILE_APPEND);

$this->output(" Preview: " . $xml_preview . "...\n");
}
}

if ($total_changed > 20) {
$this->output("\n... and " . ($total_changed - 20) . " more changed pages.\n");
$this->output("All diff files saved to /tmp/diff_*.txt\n");
}
}

// Interactive selection
if (count($this->new_pages) > 0 || count($this->changed_pages) > 0) {
$this->output("\n=== Import Options ===\n");
$this->output("1. Import new pages only (preserve all local changes)\n");
$this->output("2. Import new pages + update ALL changed pages (overwrites local changes)\n");
$this->output("3. Selective import (choose which updates to apply)\n");
$this->output("4. Cancel (no changes)\n");

// Save state for import script WITHOUT the XML object
$import_data = [
'new_pages' => $this->new_pages,
'changed_pages' => $this->changed_pages,
'xml_file' => '/tmp/new_dump.xml' // Save path instead of object
];

file_put_contents('/tmp/import_data.ser', serialize($import_data));
} else {
$this->output("\nNo changes detected. Your wiki is up to date!\n");
}
}

private function getTextContent($address) {
// Handle different content storage formats in MW 1.35+
if (strpos($address, 'tt:') === 0) {
// Text table reference
$text_id = substr($address, 3);
$result = $this->db->query("SELECT old_text FROM text WHERE old_id = $text_id");
if ($row = $result->fetch_assoc()) {
return $row['old_text'];
}
} elseif (strpos($address, 'es:') === 0) {
// External storage - would need special handling
return "[External storage content]";
}
// Direct content
return $address;
}
}

$maintClass = AnalyzeAndImport::class;
require_once RUN_MAINTENANCE_IF_MAIN;
PHP_EOF

cd /var/www/html
php /tmp/analyze_import.php
}

# Function to perform selected import
perform_import() {
local choice=$1

cat > /tmp/do_import.php << 'PHP_EOF'
<?php
require_once '/var/www/html/maintenance/Maintenance.php';

class DoImport extends Maintenance {
public function __construct() {
parent::__construct();
$this->addOption('mode', 'Import mode', true, true);
}

public function execute() {
$mode = $this->getOption('mode');
$data = unserialize(file_get_contents('/tmp/import_data.ser'));

// Load XML file
$xml = simplexml_load_file($data['xml_file']);

$new_imported = 0;
$updated = 0;

// Import new pages (always for modes 1-3)
if ($mode != '4') {
foreach ($data['new_pages'] as $title => $content) {
$this->importPage($title, $content, $xml);
$new_imported++;
$this->output("Imported new page: $title\n");
}
}

// Handle changed pages based on mode
if ($mode == '2') {
// Update all changed pages
foreach ($data['changed_pages'] as $title => $info) {
$this->output("Updating: $title\n");
if ($this->reimportPage($title, $xml)) {
$updated++;
$this->output("Updated page: $title\n");
} else {
$this->output("Failed to update: $title\n");
}
}
} elseif ($mode == '3') {
// Selective update
$this->output("\n=== Selective Import Mode ===\n");
$this->output("For each changed page, choose:\n");
$this->output(" y = yes, update this page\n");
$this->output(" n = no, keep local version\n");
$this->output(" d = show diff file\n");
$this->output(" a = update all remaining pages\n");
$this->output(" s = skip all remaining pages\n\n");

$update_all = false;
$skip_all = false;

foreach ($data['changed_pages'] as $title => $info) {
if ($skip_all) {
$this->output("Skipped: $title\n");
continue;
}

if ($update_all) {
if ($this->reimportPage($title, $xml)) {
$updated++;
$this->output("Updated: $title\n");
}
continue;
}

$this->output("\nPage: $title\n");
$this->output("Action (y/n/d/a/s): ");
$handle = fopen("php://stdin", "r");
$line = trim(fgets($handle));

while ($line == 'd') {
// Show diff
$safe_title = preg_replace('/[^a-zA-Z0-9_-]/', '_', $title);
$diff_file = "/tmp/diff_${safe_title}.txt";
if (file_exists($diff_file)) {
system("head -50 $diff_file");
$this->output("\n[Showing first 50 lines - full file at $diff_file]\n");
}
$this->output("Action (y/n/a/s): ");
$line = trim(fgets($handle));
}

if ($line == 'a') {
$update_all = true;
if ($this->reimportPage($title, $xml)) {
$updated++;
$this->output("Updated: $title\n");
}
} elseif ($line == 's') {
$skip_all = true;
$this->output("Skipped: $title\n");
} elseif ($line == 'y') {
if ($this->reimportPage($title, $xml)) {
$updated++;
$this->output("Updated: $title\n");
} else {
$this->output("Failed to update: $title\n");
}
} else {
$this->output("Skipped: $title\n");
}
}
}

$this->output("\n=== Import Complete ===\n");
$this->output("New pages imported: $new_imported\n");
$this->output("Pages updated: $updated\n");
}

private function importPage($title, $content, $xml) {
// Create single page XML for import
$tempFile = '/tmp/single_page_' . md5($title) . '.xml';
$singlePage = new SimpleXMLElement('<?xml version="1.0" encoding="utf-8"?><mediawiki></mediawiki>');

if ($xml->siteinfo) {
$siteinfo = $singlePage->addChild('siteinfo');
foreach ($xml->siteinfo->children() as $child) {
$siteinfo->addChild($child->getName(), (string)$child);
}
}

// Find and add the page
foreach ($xml->page as $page) {
if (str_replace(' ', '_', (string)$page->title) == $title) {
$newPage = $singlePage->addChild('page');
foreach ($page->children() as $child) {
if ($child->getName() == 'revision') {
$revision = $newPage->addChild('revision');
foreach ($child->children() as $revChild) {
$revision->addChild($revChild->getName(), (string)$revChild);
}
} else {
$newPage->addChild($child->getName(), (string)$child);
}
}
break;
}
}

$singlePage->asXML($tempFile);
exec("php /var/www/html/maintenance/importDump.php < $tempFile 2>&1");
unlink($tempFile);
}

private function reimportPage($title, $xml) {
// For updating existing pages, delete then reimport
$db = new mysqli('127.0.0.1', 'wikiuser', 'wikipass', 'completenoobs_wiki');

// Delete the existing page
$safe_title = $db->real_escape_string(str_replace(' ', '_', $title));
$db->query("DELETE FROM page WHERE page_title = '$safe_title' AND page_namespace = 0");

$db->close();

// Now import the new version
foreach ($xml->page as $page) {
if (str_replace(' ', '_', (string)$page->title) == $title) {
$tempFile = '/tmp/update_page_' . md5($title) . '.xml';
$singlePage = new SimpleXMLElement('<?xml version="1.0" encoding="utf-8"?><mediawiki></mediawiki>');

if ($xml->siteinfo) {
$siteinfo = $singlePage->addChild('siteinfo');
foreach ($xml->siteinfo->children() as $child) {
$siteinfo->addChild($child->getName(), (string)$child);
}
}

$newPage = $singlePage->addChild('page');
foreach ($page->children() as $child) {
if ($child->getName() == 'revision') {
$revision = $newPage->addChild('revision');
foreach ($child->children() as $revChild) {
$revision->addChild($revChild->getName(), (string)$revChild);
}
} else {
$newPage->addChild($child->getName(), (string)$child);
}
}

$singlePage->asXML($tempFile);
$result = exec("php /var/www/html/maintenance/importDump.php < $tempFile 2>&1", $output, $return);
unlink($tempFile);

return ($return === 0);
}
}

return false;
}
}

$maintClass = DoImport::class;
require_once RUN_MAINTENANCE_IF_MAIN;
PHP_EOF

cd /var/www/html
php /tmp/do_import.php --mode="$choice"
}

# Main execution
main() {
check_environment

# Start MariaDB if not running
service mariadb status > /dev/null 2>&1 || service mariadb start

# Wait for MariaDB
for i in {1..30}; do
if mysql -e "SELECT 1;" &>/dev/null; then
break
fi
sleep 1
done

CURRENT=$(get_current_version)
echo "Current version: $CURRENT"
echo ""

echo "Checking for updates..."
LATEST=$(check_for_updates 2>/dev/null)
if [ $? -ne 0 ] || [ -z "$LATEST" ] || [[ "$LATEST" == *"ERROR"* ]]; then
echo "Failed to check for updates"
exit 1
fi

echo "Latest available: $LATEST"
echo ""

# Always proceed to analysis even if versions match
# (there might be content updates in the same version)
echo "Proceeding with content analysis..."
echo ""

# Backup database
backup_database

# Download new XML
if ! download_xml "$LATEST"; then
echo "Failed to download new XML"
exit 1
fi

# Analyze differences
analyze_and_import

# Check if there are changes to import
if [ -f "/tmp/import_data.ser" ]; then
echo ""
read -p "Choose option (1-4): " -n 1 -r
echo

if [[ $REPLY =~ ^[1-4]$ ]]; then
if [ "$REPLY" != "4" ]; then
perform_import "$REPLY"

# Update version info
echo "Import: $LATEST" > /var/www/html/.last_import
echo "Date: $(date)" >> /var/www/html/.last_import

# Rebuild indices
echo "Rebuilding indices..."
php maintenance/rebuildrecentchanges.php
php maintenance/initSiteStats.php
else
echo "Update cancelled"
fi
else
echo "Invalid option. Update cancelled"
fi
fi

# Clean up temp files
rm -f /tmp/import_data.ser /tmp/update_analysis.json /tmp/diff_*.txt /tmp/analyze_import.php /tmp/do_import.php 2>/dev/null

echo ""
echo "Done!"
}

# Run main function
main "$@"
</syntaxhighlight>

=== 2.5: Entrypoint Script ===
<syntaxhighlight lang="bash">
nano entrypoint.sh
</syntaxhighlight>

<syntaxhighlight lang="bash">
#!/bin/bash

echo "Starting CompleteNoobs Wiki..."

service mariadb start

# Wait for MariaDB
for i in {1..30}; do
if mysql -e "SELECT 1;" &>/dev/null; then
echo "MariaDB ready!"
break
fi
sleep 1
done

echo ""
echo "CompleteNoobs Wiki ready at: http://localhost:8080"
echo "Admin login: admin / AdminPass123!"
echo ""
echo "Features:"
echo "- Complete wiki content imported from XML"
echo "- License notices on all pages (via PageNotice)"
echo "- SyntaxHighlight for code blocks"
echo "- YouTube video embedding"
echo "- Contribution Scores special page"
echo "- XML update system (preserves local edits)"
echo ""
echo "To check for updates: docker exec -it completenoobs_wiki /var/www/html/check_updates.sh"
echo ""

apache2-foreground
</syntaxhighlight>

== Step 3: Build and Run ==

=== 3.1: Build the Image ===
<syntaxhighlight lang="bash">
docker build -t completenoobs/wiki:latest .
</syntaxhighlight>
This will take several minutes.

=== 3.2: Run the Container ===
<syntaxhighlight lang="bash">
docker run -d -p 8080:80 \
-v completenoobs_mysql:/var/lib/mysql \
-v completenoobs_images:/var/www/html/images \
--name completenoobs_wiki completenoobs/wiki:latest
</syntaxhighlight>

* NOTE: The above <code>docker run</code> command is for quick testing, if you want to be able to export your wiki's database to an XML file you can backup and share, please use method in expanding info box below.
<div class="toccolours mw-collapsible mw-collapsed">
If you want to be able to Export Your MediaWiki Database to Dated XML File - use this <code>docker run</code> method:
<div class="mw-collapsible-content">

To export your MediaWiki database to a dated XML file (e.g., <code>20250901.xml</code>) and save it to the host’s <code>~/wiki-container</code> directory, run the export script inside the Docker container and use a volume mount to write the file to the host.<br><br>

<b>Step 1: Create Host Directory</b><br>
On the host, ensure the <code>~/wiki-container</code> directory exists:<br>
<syntaxhighlight lang="bash">
mkdir -p ~/wiki-container
</syntaxhighlight><br>

<b>Step 2: Run Container with Volume Mount</b><br>
If your container isn’t already using a volume for <code>~/wiki-container</code>, stop and remove it, then restart with a volume mount:<br>
<syntaxhighlight lang="bash">
docker stop completenoobs_wiki
docker rm completenoobs_wiki
docker run -d -p 8080:80 \
-v ~/wiki-container:/export \
-v completenoobs_mysql:/var/lib/mysql \
-v completenoobs_images:/var/www/html/images \
--name completenoobs_wiki \
completenoobs/cnoobs-wiki:0.1
</syntaxhighlight><br>

<b>Step 3: Run Export Script in Container</b><br>
Access the container’s shell:<br>
<syntaxhighlight lang="bash">
docker exec -it completenoobs_wiki bash
</syntaxhighlight>
Inside the container, run the export script to create a dated XML file:<br>
<syntaxhighlight lang="bash">
DATE=$(date +%Y%m%d)
php /var/www/html/maintenance/run.php dumpBackup.php --full --output=file:/export/$DATE.xml
exit
</syntaxhighlight>
This writes the file (e.g., <code>20250901.xml</code>) to <code>/export</code> in the container, which maps to <code>~/wiki-container</code> on the host.<br><br>

<b>Step 4: Verify the File</b><br>
On the host, check for the XML file:<br>
<syntaxhighlight lang="bash">
ls ~/wiki-container
</syntaxhighlight>
You should see a file like <code>20250901.xml</code>.<br><br>

<b>Notes</b><br>
- If you encounter permission issues, ensure the container’s user has write access to <code>/export</code>:<br>
<syntaxhighlight lang="bash">
chmod -R 777 /export
</syntaxhighlight>
- The script must be run inside the container, as it requires MediaWiki’s environment and database access.<br>
- If your container uses a different volume setup, adjust the mount point accordingly.

</div>
</div>

== Step 4: Test Everything ==

=== 4.1: Check the Wiki ===
* Visit: http://localhost:8080
* You should see the PageNotice at the top
* Login with: admin / AdminPass123!
{{:Restore_the_completenoobs_Main_Page}}

<div class="toccolours mw-collapsible mw-collapsed">
Change Admin Password:
<div class="mw-collapsible-content">

By default, the admin user's password is <code>AdminPass123!</code>. It's highly recommended to change this immediately. You can do this either through the wiki's web interface or directly in the Docker terminal.<br><br>

<b>Method 1: Change Password via Web Interface</b><br>
This is the easiest method. You can change your password directly from the wiki itself.<br>

1. Log in to your wiki with the default credentials: <code>admin</code> / <code>AdminPass123!</code>.<br>
2. Once logged in, click your username (<code>admin</code>) in the top-right corner of the page.<br>
3. From the drop-down menu, select <b>Preferences</b>.<br>
4. On the Preferences page, go to the <b>Password</b> tab.<br>
5. Enter the current password (<code>AdminPass123!</code>), then enter your new password twice.<br>
6. Click <b>Change password</b>.<br>

Your password is now changed, and you will need to use the new one for future logins.<br><br>

<b>Method 2: Change Password via Terminal (No-Email Reset)</b><br>
If you have forgotten the password or prefer to use the command line, you can reset it directly inside the Docker container using a MediaWiki maintenance script.<br>

1. <b>Access the container's shell</b> with the following command from your host machine:<br>
<syntaxhighlight lang="bash">
docker exec -it completenoobs_wiki bash
</syntaxhighlight>

2. Once inside the container, use the <code>changePassword.php</code> maintenance script to change the password. This is the modern, recommended way to run MediaWiki maintenance scripts.<br>
* Change <b>NEWPASSWORD</b> to your new password<br>
<syntaxhighlight lang="bash">
php /var/www/html/maintenance/run.php changePassword.php --user=admin --password=NEWPASSWORD
</syntaxhighlight>

3. Type <code>exit</code> to leave the container's shell.<br>

The admin password has now been reset. You can log in to your wiki with the new password.
</div>
</div>

=== 4.2: Test Extensions ===
* '''YouTube''': Edit any page, add <code><youtube>N9qYF9DZPdw</youtube></code>
* '''PageNotice''': Should already be visible at the top
* '''SyntaxHighlight''': Add code blocks with <nowiki><code><syntaxhighlight lang="python">code here</syntaxhighlight></code></nowiki>

=== 4.3: Check Status ===
<syntaxhighlight lang="bash">
docker exec completenoobs_wiki /var/www/html/check_status.sh
</syntaxhighlight>

== Step 5: XML Update Operations ==
*NOTE: update_xml.sh still needs alot of work, this just idea placeholder for now.
=== 5.1: Check for Updates (Interactive) ===
<syntaxhighlight lang="bash">
docker exec -it completenoobs_wiki /var/www/html/check_updates.sh
</syntaxhighlight>
This will:
* Check the CompleteNoobs XML repository for new dumps
* Compare with your current version
* Ask for confirmation before updating
* Import ONLY new pages (preserves your edits)
* Create a backup before making changes

=== 5.2: Force Update (Non-Interactive) ===
<syntaxhighlight lang="bash">
docker exec completenoobs_wiki bash -c "echo 'y' | /var/www/html/update_xml.sh"
</syntaxhighlight>

=== 5.3: Manual Update Process ===
<syntaxhighlight lang="bash">
# 1. Enter container
docker exec -it completenoobs_wiki bash

# 2. Check current version
cat /var/www/html/.last_import

# 3. Run update
/var/www/html/check_updates.sh

# 4. Exit container
exit
</syntaxhighlight>

== Step 6: Troubleshooting Commands ==
=== Access container shell: ===
<syntaxhighlight lang="bash">
docker exec -it completenoobs_wiki bash
</syntaxhighlight>

=== Edit configuration: ===
<syntaxhighlight lang="bash">
docker exec -it completenoobs_wiki nano /var/www/html/LocalSettings.php
</syntaxhighlight>

=== Check logs: ===
<syntaxhighlight lang="bash">
docker logs completenoobs_wiki
</syntaxhighlight>

=== View update logs: ===
<syntaxhighlight lang="bash">
docker exec completenoobs_wiki tail -f /tmp/mediawiki-debug.log
</syntaxhighlight>

=== Complete restart: ===
<syntaxhighlight lang="bash">
docker stop completenoobs_wiki
docker rm completenoobs_wiki
docker run -d -p 8080:80 \
-v completenoobs_mysql:/var/lib/mysql \
-v completenoobs_images:/var/www/html/images \
--name completenoobs_wiki completenoobs/wiki:latest
</syntaxhighlight>

== Expected Results ==
* Working wiki with imported CompleteNoobs content
* PageNotice visible at top of all pages
* All extensions functional
* Text editors (nano/vim) available in container
* Utility scripts for maintenance
* XML update system that preserves local edits

==need to add==
* way for user to backup there local custom wiki - xml exporter

Talk:Restore the completenoobs Main Page

2025-09-02T10:38:21Z

AwesomO: Created page with "* Enter in page - saves retyping <pre>{{:Restore_the_completenoobs_Main_Page}}</pre>"

* Enter in page - saves retyping
<pre>{{:Restore_the_completenoobs_Main_Page}}</pre>

CompleteNoobs Docker Image Creation

2025-09-02T10:23:46Z

AwesomO: /* 4.1: Check the Wiki */

= Complete Noobs Docker Wiki Tutorial =
* [[Docker_Install_Guide| Docker install guide]]
==errors==
* This mainly works - just need to fix the extensions popular pages and contrubtion scores
* The XML updater requires more work - currently idea placeholder

== Prerequisites ==
* Ubuntu 24.04
* Docker installed and running
* Your user in docker group: <code>sudo usermod -aG docker $USER</code> (then logout/login)

== Step 2: Create All Files ==

=== 2.1: Dockerfile ===
<syntaxhighlight lang="bash">
nano Dockerfile
</syntaxhighlight>
Copy this exactly:

<syntaxhighlight lang="dockerfile">
FROM mediawiki:1.44
# Mediawiki 1.44 used over latest because can confirm extensions youtube and pagenotice works
# Install dependencies
RUN apt-get update && apt-get install -y \
mariadb-server \
python3 \
python3-requests \
python3-bs4 \
python3-pygments \
curl \
wget \
unzip \
nano \
git \
&& apt-get clean

# Copy scripts
COPY download_latest_xml.py /usr/src/download_latest_xml.py
COPY setup_wiki.sh /usr/src/setup_wiki.sh
COPY update_xml.sh /usr/src/update_xml.sh
COPY entrypoint.sh /entrypoint.sh

# Make executable
RUN chmod +x /usr/src/setup_wiki.sh /entrypoint.sh /usr/src/update_xml.sh

# Download XML
RUN python3 /usr/src/download_latest_xml.py

# Setup wiki
RUN /usr/src/setup_wiki.sh

EXPOSE 80
VOLUME /var/lib/mysql
VOLUME /var/www/html/images

ENTRYPOINT ["/entrypoint.sh"]
</syntaxhighlight>

=== 2.2: XML Download Script ===
<syntaxhighlight lang="bash">
nano download_latest_xml.py
</syntaxhighlight>

<syntaxhighlight lang="python">
#!/usr/bin/env python3
import os
import requests
from bs4 import BeautifulSoup
import re

BASE_URL = "https://xml.completenoobs.com/xmlDumps/"

def parse_date_from_dump(dump_name):
match = re.match(r'(\d{2})_(\d{2})_(\d{2})\.Noobs', dump_name)
if match:
day, month, year = match.groups()
year_int = int(year)
full_year = 2000 + year_int if year_int <= 49 else 1900 + year_int
return (full_year, int(month), int(day))
return (0, 0, 0)

def get_available_dumps():
try:
response = requests.get(BASE_URL, timeout=30)
response.raise_for_status()
soup = BeautifulSoup(response.text, 'html.parser')
dumps = [link.get('href').rstrip('/') for link in soup.find_all('a')
if re.match(r'\d{2}_\d{2}_\d{2}\.Noobs/$', link.get('href', ''))]
return sorted(dumps, key=parse_date_from_dump, reverse=True)
except Exception as e:
print(f"Error fetching dumps: {e}")
return []

def get_dump_files(dump):
try:
response = requests.get(f"{BASE_URL}{dump}/", timeout=30)
response.raise_for_status()
soup = BeautifulSoup(response.text, 'html.parser')
files = [link.get('href') for link in soup.find_all('a')
if link.get('href', '').endswith('.xml')]
return sorted(files, reverse=True)
except Exception as e:
print(f"Error fetching dump files: {e}")
return []

def download_file(url, filename):
try:
print(f"Downloading {filename}...")
response = requests.get(url, stream=True, timeout=60)
response.raise_for_status()

total_size = int(response.headers.get('content-length', 0))
downloaded = 0

with open(filename, 'wb') as f:
for chunk in response.iter_content(chunk_size=8192):
if chunk:
f.write(chunk)
downloaded += len(chunk)
if total_size > 0:
progress = (downloaded / total_size) * 100
print(f"\rProgress: {progress:.1f}%", end='', flush=True)
print()
return True
except Exception as e:
print(f"Error downloading {filename}: {e}")
return False

def main():
print("Fetching available XML dumps...")
dumps = get_available_dumps()

if not dumps:
print("No dumps found!")
exit(1)

newest_dump = dumps[0]
print(f"Latest dump: {newest_dump}")

files = get_dump_files(newest_dump)
if not files:
print("No XML files found in latest dump!")
exit(1)

newest_xml = files[0]
xml_url = f"{BASE_URL}{newest_dump}/{newest_xml}"
local_filename = "/tmp/completenoobs_dump.xml"

if download_file(xml_url, local_filename):
print(f"Successfully downloaded {newest_xml}")
with open("/tmp/dump_info.txt", "w") as f:
f.write(f"{newest_dump}/{newest_xml}")
else:
print("Failed to download XML dump!")
exit(1)

if __name__ == "__main__":
main()
</syntaxhighlight>

=== 2.3: Main Setup Script ===
<syntaxhighlight lang="bash">
nano setup_wiki.sh
</syntaxhighlight>

<syntaxhighlight lang="bash">
#!/bin/bash
set -e

echo "Setting up CompleteNoobs Wiki..."

# Initialize MariaDB
if [ ! -d "/var/lib/mysql/mysql" ]; then
mysql_install_db --user=mysql --datadir=/var/lib/mysql
fi

service mariadb start

# Wait for MariaDB
for i in {1..30}; do
if mysql -e "SELECT 1;" &>/dev/null; then
echo "MariaDB ready!"
break
fi
sleep 2
done

# Setup database
mysql -e "CREATE DATABASE IF NOT EXISTS completenoobs_wiki CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
mysql -e "CREATE USER IF NOT EXISTS 'wikiuser'@'127.0.0.1' IDENTIFIED BY 'wikipass';"
mysql -e "GRANT ALL PRIVILEGES ON completenoobs_wiki.* TO 'wikiuser'@'127.0.0.1';"
mysql -e "CREATE USER IF NOT EXISTS 'wikiuser'@'localhost' IDENTIFIED BY 'wikipass';"
mysql -e "GRANT ALL PRIVILEGES ON completenoobs_wiki.* TO 'wikiuser'@'localhost';"
mysql -e "FLUSH PRIVILEGES;"

# Install MediaWiki
cd /var/www/html
php maintenance/install.php \
--dbtype=mysql \
--dbserver=127.0.0.1 \
--dbname=completenoobs_wiki \
--dbuser=wikiuser \
--dbpass=wikipass \
--server="http://localhost:8080" \
--scriptpath="" \
--lang=en \
--pass=AdminPass123! \
"CompleteNoobs Wiki" \
"admin"

# Download and install extensions
cd extensions/
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/PageNotice --branch REL1_44 || echo "PageNotice download failed, continuing..."
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/YouTube --branch REL1_44 || echo "YouTube download failed, continuing..."
cd /var/www/html

# Configure LocalSettings.php
cat >> LocalSettings.php << 'EOF'
# Basic settings
$wgEnableUploads = true;
$wgUseImageMagick = true;
$wgImageMagickConvertCommand = "/usr/bin/convert";
$wgDefaultSkin = "vector-2022";
$wgAllowExternalImages = true;

# Debug (can be removed later)
$wgShowExceptionDetails = true;
$wgDebugLogFile = "/tmp/mediawiki-debug.log";

# PageNotice extension (if available)
if ( file_exists( "$IP/extensions/PageNotice/extension.json" ) ) {
wfLoadExtension( 'PageNotice' );
}

# YouTube extension (if available)
if ( file_exists( "$IP/extensions/YouTube/extension.json" ) ) {
wfLoadExtension( 'YouTube' );
}

# SyntaxHighlight (usually bundled)
if ( file_exists( "$IP/extensions/SyntaxHighlight_GeSHi/extension.json" ) ) {
wfLoadExtension( 'SyntaxHighlight_GeSHi' );
$wgPygmentizePath = '/usr/bin/pygmentize';
}
EOF

# Import XML dump if available
if [ -f "/tmp/completenoobs_dump.xml" ]; then
echo "Importing XML dump..."

if php maintenance/importDump.php --uploads < /tmp/completenoobs_dump.xml; then
echo "XML import completed!"
else
echo "XML import had warnings"
fi

# Basic maintenance
php maintenance/update.php --quick || echo "Update completed with warnings"
php maintenance/rebuildrecentchanges.php || echo "RecentChanges rebuilt with warnings"
php maintenance/initSiteStats.php || echo "SiteStats initialized with warnings"

if [ -f "/tmp/dump_info.txt" ]; then
echo "Import: $(cat /tmp/dump_info.txt)" > /var/www/html/.last_import
echo "Date: $(date)" >> /var/www/html/.last_import
fi
else
echo "No XML dump found - starting with empty wiki"
fi

# Copy update script to accessible location
cp /usr/src/update_xml.sh /var/www/html/update_xml.sh
chmod +x /var/www/html/update_xml.sh

# Create user-friendly update wrapper
cat > /var/www/html/check_updates.sh << 'UPDATE_WRAPPER_EOF'
#!/bin/bash
echo "=== CompleteNoobs Wiki Update Checker ==="
echo ""
echo "This tool checks for new content from the CompleteNoobs XML repository"
echo "and imports ONLY new pages, preserving all your local edits."
echo ""

/var/www/html/update_xml.sh
UPDATE_WRAPPER_EOF
chmod +x /var/www/html/check_updates.sh

# Create simple status script
cat > /var/www/html/check_status.sh << 'STATUS_EOF'
#!/bin/bash
cd /var/www/html
echo "=== Wiki Status ==="
echo "Pages: $(mysql --user=wikiuser --password=wikipass completenoobs_wiki -e "SELECT COUNT(*) FROM page;" -s -N 2>/dev/null || echo "Error")"
echo "Users: $(mysql --user=wikiuser --password=wikipass completenoobs_wiki -e "SELECT COUNT(*) FROM user WHERE user_id > 0;" -s -N 2>/dev/null || echo "Error")"
echo ""
echo "=== Extensions ==="
if [ -d "extensions/PageNotice" ]; then
echo "PageNotice: Installed"
else
echo "PageNotice: Not installed"
fi
if [ -d "extensions/YouTube" ]; then
echo "YouTube: Installed"
else
echo "YouTube: Not installed"
fi
if [ -d "extensions/ContributionScores" ]; then
echo "ContributionScores: Installed"
else
echo "ContributionScores: Not installed"
fi
echo ""
echo "=== Update System ==="
if [ -f ".last_import" ]; then
echo "Current version: $(grep 'Import:' .last_import | cut -d' ' -f2)"
echo "Import date: $(grep 'Date:' .last_import | cut -d' ' -f2-)"
else
echo "No version info available"
fi
echo ""
echo "To check for updates: docker exec -it completenoobs_wiki /var/www/html/check_updates.sh"
STATUS_EOF
chmod +x /var/www/html/check_status.sh

echo ""
echo "Setup completed!"
echo "Admin: admin / AdminPass123!"
echo "Update scripts installed:"
echo "- /var/www/html/check_updates.sh (user-friendly)"
echo "- /var/www/html/update_xml.sh (direct)"

# Final counts
PAGES=$(mysql --user=wikiuser --password=wikipass completenoobs_wiki -e "SELECT COUNT(*) FROM page;" -s -N 2>/dev/null || echo "0")
echo "Pages imported: $PAGES"

service mariadb stop
</syntaxhighlight>

=== 2.4: XML Update Script ===
<syntaxhighlight lang="bash">
nano update_xml.sh
</syntaxhighlight>

<syntaxhighlight lang="bash">
#!/bin/bash
set -e

echo "=== CompleteNoobs Wiki XML Updater ==="
echo "This will check for new and updated pages"
echo ""

# Function to check if running in container
check_environment() {
if [ ! -f "/var/www/html/LocalSettings.php" ]; then
echo "Error: This script must be run inside the wiki container"
exit 1
fi
}

# Function to get current XML version
get_current_version() {
if [ -f "/var/www/html/.last_import" ]; then
grep "Import:" /var/www/html/.last_import | cut -d' ' -f2
else
echo "none"
fi
}

# Function to check for updates
check_for_updates() {
python3 - << 'PYTHON_EOF'
import requests
from bs4 import BeautifulSoup
import re
import sys

BASE_URL = "https://xml.completenoobs.com/xmlDumps/"

def parse_date_from_dump(dump_name):
match = re.match(r'(\d{2})_(\d{2})_(\d{2})\.Noobs', dump_name)
if match:
day, month, year = match.groups()
year_int = int(year)
full_year = 2000 + year_int if year_int <= 49 else 1900 + year_int
return (full_year, int(month), int(day))
return (0, 0, 0)

def get_latest_dump():
try:
response = requests.get(BASE_URL, timeout=30)
response.raise_for_status()
soup = BeautifulSoup(response.text, 'html.parser')
dumps = [link.get('href').rstrip('/') for link in soup.find_all('a')
if re.match(r'\d{2}_\d{2}_\d{2}\.Noobs/$', link.get('href', ''))]
if dumps:
latest = sorted(dumps, key=parse_date_from_dump, reverse=True)[0]

# Get XML files from latest dump
response = requests.get(f"{BASE_URL}{latest}/", timeout=30)
response.raise_for_status()
soup = BeautifulSoup(response.text, 'html.parser')
files = [link.get('href') for link in soup.find_all('a')
if link.get('href', '').endswith('.xml')]

if files:
newest_xml = sorted(files, reverse=True)[0]
print(f"{latest}/{newest_xml}")
sys.exit(0)
except Exception as e:
print(f"ERROR: {e}", file=sys.stderr)
sys.exit(1)

print("ERROR: No dumps found", file=sys.stderr)
sys.exit(1)

get_latest_dump()
PYTHON_EOF
}

# Function to download new XML
download_xml() {
local dump_info="$1"
local dump_dir=$(echo "$dump_info" | cut -d'/' -f1)
local xml_file=$(echo "$dump_info" | cut -d'/' -f2)
local url="https://xml.completenoobs.com/xmlDumps/${dump_info}"

echo "Downloading: $xml_file"
echo "From: $dump_dir"
echo "URL: $url"

if wget -O /tmp/new_dump.xml "$url" --progress=bar:force 2>&1; then
echo "Download successful!"
return 0
else
echo "Download failed!"
return 1
fi
}

# Function to backup current database
backup_database() {
echo "Creating database backup..."
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
mysqldump --user=wikiuser --password=wikipass completenoobs_wiki > /tmp/wiki_backup_${TIMESTAMP}.sql
echo "Backup created: /tmp/wiki_backup_${TIMESTAMP}.sql"
}

# Function to analyze and import changes
analyze_and_import() {
echo "Analyzing differences between XML and local wiki..."

# Create analysis and import script for MediaWiki 1.44+
cat > /tmp/analyze_import.php << 'PHP_EOF'
<?php
require_once '/var/www/html/maintenance/Maintenance.php';

class AnalyzeAndImport extends Maintenance {
private $db;
private $new_pages = [];
private $changed_pages = [];
private $unchanged_pages = [];

public function __construct() {
parent::__construct();
$this->addDescription('Analyze and selectively import from XML dump');
}

public function execute() {
$this->db = new mysqli('127.0.0.1', 'wikiuser', 'wikipass', 'completenoobs_wiki');

// MediaWiki 1.35+ uses slots and content tables
// Get existing pages with their content
$query = "
SELECT p.page_title, p.page_id, c.content_address, c.content_sha1
FROM page p
JOIN revision r ON p.page_latest = r.rev_id
JOIN slots s ON r.rev_id = s.slot_revision_id
JOIN slot_roles sr ON s.slot_role_id = sr.role_id
JOIN content c ON s.slot_content_id = c.content_id
WHERE p.page_namespace = 0 AND sr.role_name = 'main'
";

$result = $this->db->query($query);
if (!$result) {
$this->error("Database query failed: " . $this->db->error);
return;
}

$existing = [];
while ($row = $result->fetch_assoc()) {
// Get actual text content
$text_content = $this->getTextContent($row['content_address']);
$existing[$row['page_title']] = [
'id' => $row['page_id'],
'content' => $text_content,
'sha1' => $row['content_sha1']
];
}

// Parse XML and compare
$xml = simplexml_load_file('/tmp/new_dump.xml');

foreach ($xml->page as $page) {
$title = str_replace(' ', '_', (string)$page->title);
$xml_content = (string)$page->revision->text;

if (!isset($existing[$title])) {
// New page
$this->new_pages[$title] = $xml_content;
} else {
// Compare content using SHA1 for efficiency
$xml_sha1 = sha1($xml_content);

if ($existing[$title]['sha1'] !== $xml_sha1) {
// Content is different
$this->changed_pages[$title] = [
'local' => $existing[$title]['content'],
'xml' => $xml_content,
'page_id' => $existing[$title]['id']
];
} else {
$this->unchanged_pages[] = $title;
}
}
}

// Display summary
$this->output("\n=== Update Analysis ===\n");
$this->output("New pages to import: " . count($this->new_pages) . "\n");
$this->output("Changed pages found: " . count($this->changed_pages) . "\n");
$this->output("Unchanged pages: " . count($this->unchanged_pages) . "\n");

// Save analysis for review
file_put_contents('/tmp/update_analysis.json', json_encode([
'new' => array_keys($this->new_pages),
'changed' => array_keys($this->changed_pages),
'unchanged' => $this->unchanged_pages
], JSON_PRETTY_PRINT));

// Show changed pages with preview (limit to first 20 for readability)
if (count($this->changed_pages) > 0) {
$this->output("\n=== Changed Pages ===\n");
$count = 0;
$total_changed = count($this->changed_pages);

foreach ($this->changed_pages as $title => $data) {
$count++;
if ($count <= 20) {
$this->output("\n$count. $title\n");

// Create a simple diff preview (first 300 chars)
$xml_preview = substr($data['xml'], 0, 100);

// Save full diff to file
$safe_title = preg_replace('/[^a-zA-Z0-9_-]/', '_', $title);
$diff_file = "/tmp/diff_${safe_title}.txt";
file_put_contents($diff_file, "=== FULL DIFF FOR: $title ===\n\n");
file_put_contents($diff_file, "--- LOCAL VERSION ---\n", FILE_APPEND);
file_put_contents($diff_file, $data['local'] . "\n\n", FILE_APPEND);
file_put_contents($diff_file, "--- XML VERSION ---\n", FILE_APPEND);
file_put_contents($diff_file, $data['xml'], FILE_APPEND);

$this->output(" Preview: " . $xml_preview . "...\n");
}
}

if ($total_changed > 20) {
$this->output("\n... and " . ($total_changed - 20) . " more changed pages.\n");
$this->output("All diff files saved to /tmp/diff_*.txt\n");
}
}

// Interactive selection
if (count($this->new_pages) > 0 || count($this->changed_pages) > 0) {
$this->output("\n=== Import Options ===\n");
$this->output("1. Import new pages only (preserve all local changes)\n");
$this->output("2. Import new pages + update ALL changed pages (overwrites local changes)\n");
$this->output("3. Selective import (choose which updates to apply)\n");
$this->output("4. Cancel (no changes)\n");

// Save state for import script WITHOUT the XML object
$import_data = [
'new_pages' => $this->new_pages,
'changed_pages' => $this->changed_pages,
'xml_file' => '/tmp/new_dump.xml' // Save path instead of object
];

file_put_contents('/tmp/import_data.ser', serialize($import_data));
} else {
$this->output("\nNo changes detected. Your wiki is up to date!\n");
}
}

private function getTextContent($address) {
// Handle different content storage formats in MW 1.35+
if (strpos($address, 'tt:') === 0) {
// Text table reference
$text_id = substr($address, 3);
$result = $this->db->query("SELECT old_text FROM text WHERE old_id = $text_id");
if ($row = $result->fetch_assoc()) {
return $row['old_text'];
}
} elseif (strpos($address, 'es:') === 0) {
// External storage - would need special handling
return "[External storage content]";
}
// Direct content
return $address;
}
}

$maintClass = AnalyzeAndImport::class;
require_once RUN_MAINTENANCE_IF_MAIN;
PHP_EOF

cd /var/www/html
php /tmp/analyze_import.php
}

# Function to perform selected import
perform_import() {
local choice=$1

cat > /tmp/do_import.php << 'PHP_EOF'
<?php
require_once '/var/www/html/maintenance/Maintenance.php';

class DoImport extends Maintenance {
public function __construct() {
parent::__construct();
$this->addOption('mode', 'Import mode', true, true);
}

public function execute() {
$mode = $this->getOption('mode');
$data = unserialize(file_get_contents('/tmp/import_data.ser'));

// Load XML file
$xml = simplexml_load_file($data['xml_file']);

$new_imported = 0;
$updated = 0;

// Import new pages (always for modes 1-3)
if ($mode != '4') {
foreach ($data['new_pages'] as $title => $content) {
$this->importPage($title, $content, $xml);
$new_imported++;
$this->output("Imported new page: $title\n");
}
}

// Handle changed pages based on mode
if ($mode == '2') {
// Update all changed pages
foreach ($data['changed_pages'] as $title => $info) {
$this->output("Updating: $title\n");
if ($this->reimportPage($title, $xml)) {
$updated++;
$this->output("Updated page: $title\n");
} else {
$this->output("Failed to update: $title\n");
}
}
} elseif ($mode == '3') {
// Selective update
$this->output("\n=== Selective Import Mode ===\n");
$this->output("For each changed page, choose:\n");
$this->output(" y = yes, update this page\n");
$this->output(" n = no, keep local version\n");
$this->output(" d = show diff file\n");
$this->output(" a = update all remaining pages\n");
$this->output(" s = skip all remaining pages\n\n");

$update_all = false;
$skip_all = false;

foreach ($data['changed_pages'] as $title => $info) {
if ($skip_all) {
$this->output("Skipped: $title\n");
continue;
}

if ($update_all) {
if ($this->reimportPage($title, $xml)) {
$updated++;
$this->output("Updated: $title\n");
}
continue;
}

$this->output("\nPage: $title\n");
$this->output("Action (y/n/d/a/s): ");
$handle = fopen("php://stdin", "r");
$line = trim(fgets($handle));

while ($line == 'd') {
// Show diff
$safe_title = preg_replace('/[^a-zA-Z0-9_-]/', '_', $title);
$diff_file = "/tmp/diff_${safe_title}.txt";
if (file_exists($diff_file)) {
system("head -50 $diff_file");
$this->output("\n[Showing first 50 lines - full file at $diff_file]\n");
}
$this->output("Action (y/n/a/s): ");
$line = trim(fgets($handle));
}

if ($line == 'a') {
$update_all = true;
if ($this->reimportPage($title, $xml)) {
$updated++;
$this->output("Updated: $title\n");
}
} elseif ($line == 's') {
$skip_all = true;
$this->output("Skipped: $title\n");
} elseif ($line == 'y') {
if ($this->reimportPage($title, $xml)) {
$updated++;
$this->output("Updated: $title\n");
} else {
$this->output("Failed to update: $title\n");
}
} else {
$this->output("Skipped: $title\n");
}
}
}

$this->output("\n=== Import Complete ===\n");
$this->output("New pages imported: $new_imported\n");
$this->output("Pages updated: $updated\n");
}

private function importPage($title, $content, $xml) {
// Create single page XML for import
$tempFile = '/tmp/single_page_' . md5($title) . '.xml';
$singlePage = new SimpleXMLElement('<?xml version="1.0" encoding="utf-8"?><mediawiki></mediawiki>');

if ($xml->siteinfo) {
$siteinfo = $singlePage->addChild('siteinfo');
foreach ($xml->siteinfo->children() as $child) {
$siteinfo->addChild($child->getName(), (string)$child);
}
}

// Find and add the page
foreach ($xml->page as $page) {
if (str_replace(' ', '_', (string)$page->title) == $title) {
$newPage = $singlePage->addChild('page');
foreach ($page->children() as $child) {
if ($child->getName() == 'revision') {
$revision = $newPage->addChild('revision');
foreach ($child->children() as $revChild) {
$revision->addChild($revChild->getName(), (string)$revChild);
}
} else {
$newPage->addChild($child->getName(), (string)$child);
}
}
break;
}
}

$singlePage->asXML($tempFile);
exec("php /var/www/html/maintenance/importDump.php < $tempFile 2>&1");
unlink($tempFile);
}

private function reimportPage($title, $xml) {
// For updating existing pages, delete then reimport
$db = new mysqli('127.0.0.1', 'wikiuser', 'wikipass', 'completenoobs_wiki');

// Delete the existing page
$safe_title = $db->real_escape_string(str_replace(' ', '_', $title));
$db->query("DELETE FROM page WHERE page_title = '$safe_title' AND page_namespace = 0");

$db->close();

// Now import the new version
foreach ($xml->page as $page) {
if (str_replace(' ', '_', (string)$page->title) == $title) {
$tempFile = '/tmp/update_page_' . md5($title) . '.xml';
$singlePage = new SimpleXMLElement('<?xml version="1.0" encoding="utf-8"?><mediawiki></mediawiki>');

if ($xml->siteinfo) {
$siteinfo = $singlePage->addChild('siteinfo');
foreach ($xml->siteinfo->children() as $child) {
$siteinfo->addChild($child->getName(), (string)$child);
}
}

$newPage = $singlePage->addChild('page');
foreach ($page->children() as $child) {
if ($child->getName() == 'revision') {
$revision = $newPage->addChild('revision');
foreach ($child->children() as $revChild) {
$revision->addChild($revChild->getName(), (string)$revChild);
}
} else {
$newPage->addChild($child->getName(), (string)$child);
}
}

$singlePage->asXML($tempFile);
$result = exec("php /var/www/html/maintenance/importDump.php < $tempFile 2>&1", $output, $return);
unlink($tempFile);

return ($return === 0);
}
}

return false;
}
}

$maintClass = DoImport::class;
require_once RUN_MAINTENANCE_IF_MAIN;
PHP_EOF

cd /var/www/html
php /tmp/do_import.php --mode="$choice"
}

# Main execution
main() {
check_environment

# Start MariaDB if not running
service mariadb status > /dev/null 2>&1 || service mariadb start

# Wait for MariaDB
for i in {1..30}; do
if mysql -e "SELECT 1;" &>/dev/null; then
break
fi
sleep 1
done

CURRENT=$(get_current_version)
echo "Current version: $CURRENT"
echo ""

echo "Checking for updates..."
LATEST=$(check_for_updates 2>/dev/null)
if [ $? -ne 0 ] || [ -z "$LATEST" ] || [[ "$LATEST" == *"ERROR"* ]]; then
echo "Failed to check for updates"
exit 1
fi

echo "Latest available: $LATEST"
echo ""

# Always proceed to analysis even if versions match
# (there might be content updates in the same version)
echo "Proceeding with content analysis..."
echo ""

# Backup database
backup_database

# Download new XML
if ! download_xml "$LATEST"; then
echo "Failed to download new XML"
exit 1
fi

# Analyze differences
analyze_and_import

# Check if there are changes to import
if [ -f "/tmp/import_data.ser" ]; then
echo ""
read -p "Choose option (1-4): " -n 1 -r
echo

if [[ $REPLY =~ ^[1-4]$ ]]; then
if [ "$REPLY" != "4" ]; then
perform_import "$REPLY"

# Update version info
echo "Import: $LATEST" > /var/www/html/.last_import
echo "Date: $(date)" >> /var/www/html/.last_import

# Rebuild indices
echo "Rebuilding indices..."
php maintenance/rebuildrecentchanges.php
php maintenance/initSiteStats.php
else
echo "Update cancelled"
fi
else
echo "Invalid option. Update cancelled"
fi
fi

# Clean up temp files
rm -f /tmp/import_data.ser /tmp/update_analysis.json /tmp/diff_*.txt /tmp/analyze_import.php /tmp/do_import.php 2>/dev/null

echo ""
echo "Done!"
}

# Run main function
main "$@"
</syntaxhighlight>

=== 2.5: Entrypoint Script ===
<syntaxhighlight lang="bash">
nano entrypoint.sh
</syntaxhighlight>

<syntaxhighlight lang="bash">
#!/bin/bash

echo "Starting CompleteNoobs Wiki..."

service mariadb start

# Wait for MariaDB
for i in {1..30}; do
if mysql -e "SELECT 1;" &>/dev/null; then
echo "MariaDB ready!"
break
fi
sleep 1
done

echo ""
echo "CompleteNoobs Wiki ready at: http://localhost:8080"
echo "Admin login: admin / AdminPass123!"
echo ""
echo "Features:"
echo "- Complete wiki content imported from XML"
echo "- License notices on all pages (via PageNotice)"
echo "- SyntaxHighlight for code blocks"
echo "- YouTube video embedding"
echo "- Contribution Scores special page"
echo "- XML update system (preserves local edits)"
echo ""
echo "To check for updates: docker exec -it completenoobs_wiki /var/www/html/check_updates.sh"
echo ""

apache2-foreground
</syntaxhighlight>

== Step 3: Build and Run ==

=== 3.1: Build the Image ===
<syntaxhighlight lang="bash">
docker build -t completenoobs/wiki:latest .
</syntaxhighlight>
This will take several minutes.

=== 3.2: Run the Container ===
<syntaxhighlight lang="bash">
docker run -d -p 8080:80 \
-v completenoobs_mysql:/var/lib/mysql \
-v completenoobs_images:/var/www/html/images \
--name completenoobs_wiki completenoobs/wiki:latest
</syntaxhighlight>

* NOTE: The above <code>docker run</code> command is for quick testing, if you want to be able to export your wiki's database to an XML file you can backup and share, please use method in expanding info box below.
<div class="toccolours mw-collapsible mw-collapsed">
If you want to be able to Export Your MediaWiki Database to Dated XML File - use this <code>docker run</code> method:
<div class="mw-collapsible-content">

To export your MediaWiki database to a dated XML file (e.g., <code>20250901.xml</code>) and save it to the host’s <code>~/wiki-container</code> directory, run the export script inside the Docker container and use a volume mount to write the file to the host.<br><br>

<b>Step 1: Create Host Directory</b><br>
On the host, ensure the <code>~/wiki-container</code> directory exists:<br>
<syntaxhighlight lang="bash">
mkdir -p ~/wiki-container
</syntaxhighlight><br>

<b>Step 2: Run Container with Volume Mount</b><br>
If your container isn’t already using a volume for <code>~/wiki-container</code>, stop and remove it, then restart with a volume mount:<br>
<syntaxhighlight lang="bash">
docker stop completenoobs_wiki
docker rm completenoobs_wiki
docker run -d -p 8080:80 \
-v ~/wiki-container:/export \
-v completenoobs_mysql:/var/lib/mysql \
-v completenoobs_images:/var/www/html/images \
--name completenoobs_wiki \
completenoobs/cnoobs-wiki:0.1
</syntaxhighlight><br>

<b>Step 3: Run Export Script in Container</b><br>
Access the container’s shell:<br>
<syntaxhighlight lang="bash">
docker exec -it completenoobs_wiki bash
</syntaxhighlight>
Inside the container, run the export script to create a dated XML file:<br>
<syntaxhighlight lang="bash">
DATE=$(date +%Y%m%d)
php /var/www/html/maintenance/run.php dumpBackup.php --full --output=file:/export/$DATE.xml
exit
</syntaxhighlight>
This writes the file (e.g., <code>20250901.xml</code>) to <code>/export</code> in the container, which maps to <code>~/wiki-container</code> on the host.<br><br>

<b>Step 4: Verify the File</b><br>
On the host, check for the XML file:<br>
<syntaxhighlight lang="bash">
ls ~/wiki-container
</syntaxhighlight>
You should see a file like <code>20250901.xml</code>.<br><br>

<b>Notes</b><br>
- If you encounter permission issues, ensure the container’s user has write access to <code>/export</code>:<br>
<syntaxhighlight lang="bash">
chmod -R 777 /export
</syntaxhighlight>
- The script must be run inside the container, as it requires MediaWiki’s environment and database access.<br>
- If your container uses a different volume setup, adjust the mount point accordingly.

</div>
</div>

== Step 4: Test Everything ==

=== 4.1: Check the Wiki ===
* Visit: http://localhost:8080
* You should see the PageNotice at the top
* Login with: admin / AdminPass123!
{{:Restore_the_completenoobs_Main_Page}}

<div class="toccolours mw-collapsible mw-collapsed">
Change Admin Password:
<div class="mw-collapsible-content">

By default, the admin user's password is <code>AdminPass123!</code>. It's highly recommended to change this immediately. You can do this either through the wiki's web interface or directly in the Docker terminal.<br><br>

<b>Method 1: Change Password via Web Interface</b><br>
This is the easiest method. You can change your password directly from the wiki itself.<br>

1. Log in to your wiki with the default credentials: <code>admin</code> / <code>AdminPass123!</code>.<br>
2. Once logged in, click your username (<code>admin</code>) in the top-right corner of the page.<br>
3. From the drop-down menu, select <b>Preferences</b>.<br>
4. On the Preferences page, go to the <b>Password</b> tab.<br>
5. Enter the current password (<code>AdminPass123!</code>), then enter your new password twice.<br>
6. Click <b>Change password</b>.<br>

Your password is now changed, and you will need to use the new one for future logins.<br><br>

<b>Method 2: Change Password via Terminal (No-Email Reset)</b><br>
If you have forgotten the password or prefer to use the command line, you can reset it directly inside the Docker container using a MediaWiki maintenance script.<br>

1. <b>Access the container's shell</b> with the following command from your host machine:<br>
<syntaxhighlight lang="bash">
docker exec -it completenoobs_wiki bash
</syntaxhighlight>

2. Once inside the container, use the <code>changePassword.php</code> maintenance script to change the password. This is the modern, recommended way to run MediaWiki maintenance scripts.<br>
* Change <b>NEWPASSWORD</b> to your new password<br>
<syntaxhighlight lang="bash">
php /var/www/html/maintenance/run.php changePassword.php --user=admin --password=NEWPASSWORD
</syntaxhighlight>

3. Type <code>exit</code> to leave the container's shell.<br>

The admin password has now been reset. You can log in to your wiki with the new password.
</div>
</div>

=== 4.2: Test Extensions ===
* '''YouTube''': Edit any page, add <code><youtube>N9qYF9DZPdw</youtube></code>
* '''PageNotice''': Should already be visible at the top
* '''SyntaxHighlight''': Add code blocks with <nowiki><code><syntaxhighlight lang="python">code here</syntaxhighlight></code></nowiki>

=== 4.3: Check Status ===
<syntaxhighlight lang="bash">
docker exec completenoobs_wiki /var/www/html/check_status.sh
</syntaxhighlight>

== Step 5: XML Update Operations ==
*NOTE: update_xml.sh still needs alot of work, this just idea placeholder for now.
=== 5.1: Check for Updates (Interactive) ===
<syntaxhighlight lang="bash">
docker exec -it completenoobs_wiki /var/www/html/check_updates.sh
</syntaxhighlight>
This will:
* Check the CompleteNoobs XML repository for new dumps
* Compare with your current version
* Ask for confirmation before updating
* Import ONLY new pages (preserves your edits)
* Create a backup before making changes

=== 5.2: Force Update (Non-Interactive) ===
<syntaxhighlight lang="bash">
docker exec completenoobs_wiki bash -c "echo 'y' | /var/www/html/update_xml.sh"
</syntaxhighlight>

=== 5.3: Manual Update Process ===
<syntaxhighlight lang="bash">
# 1. Enter container
docker exec -it completenoobs_wiki bash

# 2. Check current version
cat /var/www/html/.last_import

# 3. Run update
/var/www/html/check_updates.sh

# 4. Exit container
exit
</syntaxhighlight>

== Step 6: Troubleshooting Commands ==
=== Access container shell: ===
<syntaxhighlight lang="bash">
docker exec -it completenoobs_wiki bash
</syntaxhighlight>

=== Edit configuration: ===
<syntaxhighlight lang="bash">
docker exec -it completenoobs_wiki nano /var/www/html/LocalSettings.php
</syntaxhighlight>

=== Check logs: ===
<syntaxhighlight lang="bash">
docker logs completenoobs_wiki
</syntaxhighlight>

=== View update logs: ===
<syntaxhighlight lang="bash">
docker exec completenoobs_wiki tail -f /tmp/mediawiki-debug.log
</syntaxhighlight>

=== Complete restart: ===
<syntaxhighlight lang="bash">
docker stop completenoobs_wiki
docker rm completenoobs_wiki
docker run -d -p 8080:80 \
-v completenoobs_mysql:/var/lib/mysql \
-v completenoobs_images:/var/www/html/images \
--name completenoobs_wiki completenoobs/wiki:latest
</syntaxhighlight>

== Expected Results ==
* Working wiki with imported CompleteNoobs content
* PageNotice visible at top of all pages
* All extensions functional
* Text editors (nano/vim) available in container
* Utility scripts for maintenance
* XML update system that preserves local edits

==need to add==
* way for user to backup there local custom wiki - xml exporter

Restore the completenoobs Main Page

2025-09-02T10:21:02Z

AwesomO: Created page with "<div class="toccolours mw-collapsible mw-collapsed"> Restore the completenoobs Main Page: <div class="mw-collapsible-content"> By default, the <code>completenoobs</code> MediaWiki instance overwrites the Main Page with content like "<strong>MediaWiki has been installed.</strong>" To revert to the page’s state before this change, undo the initial revision:<br><br> 1. Go to <code>http://localhost:8080</code> in your browser.<br> 2. On the Main Page, click <b>View Histo..."

<div class="toccolours mw-collapsible mw-collapsed">
Restore the completenoobs Main Page:
<div class="mw-collapsible-content">

By default, the <code>completenoobs</code> MediaWiki instance overwrites the Main Page with content like "<strong>MediaWiki has been installed.</strong>" To revert to the page’s state before this change, undo the initial revision:<br><br>

1. Go to <code>http://localhost:8080</code> in your browser.<br>
2. On the Main Page, click <b>View History</b> (top-right corner).<br>
3. Find the top revision by <code>MediaWiki default</code> and click <b>Undo</b>.<br>
4. Scroll down and click <b>Save changes</b> to revert the Main Page.<br><br>
</div>
</div>

Ubuntu2404 Install Docker and Docker Compose

2025-09-01T21:16:15Z

AwesomO: /* Install First Container/Image */

=== Preparation ===

Before we begin, make sure you're logged in with a user account that has sudo privileges.

=== Update System Packages ===

Update your package list to ensure you have the latest versions of packages:

<source lang="bash">
sudo apt update && sudo apt upgrade -y
</source>

=== Install Docker Prerequisites ===

Install the necessary packages for Docker setup:

<source lang="bash">
sudo apt install -y apt-transport-https ca-certificates curl software-properties-common
</source>

=== Setup Docker Repository ===

* '''Add Docker's Official GPG Key''':

<source lang="bash">
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
</source>

* '''Add the Docker Repository''':

<source lang="bash">
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
</source>

=== Install Docker and Docker Compose ===

* '''Update Package List Again''':

<source lang="bash">
sudo apt update
</source>

* '''Install Docker Engine, CLI, Containerd, and Additional Tools''':

<source lang="bash">
sudo apt install -y docker-ce docker-ce-cli containerd.io python3-bs4 python3-requests docker-compose
</source>



=== Verify Installation ===

Check if Docker and Docker Compose are installed correctly:

<source lang="bash">
docker --version
docker-compose --version
</source>

=== Configure User Permissions ===

To run Docker commands without <code>sudo</code>, add your user to the <code>docker</code> group:

<source lang="bash">
sudo usermod -aG docker $USER
</source>

'''Note''': After adding your user to the docker group, you'll need to '''log out and log back in''' for the changes to take effect.
If you do not log out and back in, Or you do not add your $USER to the docker group, you will be required to use sudo in some cases. such as ..

<div class="toccolours mw-collapsible mw-collapsed">
a way to apply group changes without logging out and back in - tip:
<div class="mw-collapsible-content">
<pre>
exec sudo su -l $USER
</pre>

This command will replace your current shell with a new login shell for your user, which will have the updated group memberships. Both of these methods will apply the group changes immediately, allowing you to use LXD commands without having to log out and back in.

<b>Remember</b>, these changes only apply to the current terminal session. If you open a new terminal window, you might need to run the command again or log out and back in for the changes to take effect system-wide.
</div>
</div>

===If Installing Docker messed up your LXC/LXD Networking===
To resolve networking conflicts between Docker and LXC containers on Ubuntu 24.04, enable IP forwarding on the host system:
* Open the sysctl configuration file in your preferred editor
<code>sudo $EDITOR /etc/sysctl.conf</code>
* Uncomment or add the following line (around line 28):
<pre>net.ipv4.ip_forward=1</pre>
* Apply the updated configuration to enable IP forwarding:
<code>sysctl -p</code><br>
* Restart the system to ensure all changes take effect.

This should resolve the networking issue for LXC containers when Docker is installed.

==Install First Container/Image==

Download the completenoobs container image, mediawiki with the completenoobs xml installed.

<code>docker pull completenoobs/cnoobs-wiki:0.1</code>

===Run container===

* Quick Start
<code>docker run -d -p 8080:80 completenoobs/cnoobs-wiki:0.1</code>

* Quick Start with Persistent Storage
<pre>
docker run -d -p 8080:80 \
-v completenoobs_mysql:/var/lib/mysql \
-v completenoobs_images:/var/www/html/images \
--name completenoobs_wiki \
completenoobs/cnoobs-wiki:0.1
</pre>

* NOTE: The above <code>docker run</code> command is for quick testing, if you want to be able to export your wiki's database to an XML file you can backup and share, please use method in expanding info box below.
<div class="toccolours mw-collapsible mw-collapsed">
If you want to be able to Export Your MediaWiki Database to Dated XML File - use this <code>docker run</code> method:
<div class="mw-collapsible-content">

To export your MediaWiki database to a dated XML file (e.g., <code>20250901.xml</code>) and save it to the host’s <code>~/wiki-container</code> directory, run the export script inside the Docker container and use a volume mount to write the file to the host.<br><br>

<b>Step 1: Create Host Directory</b><br>
On the host, ensure the <code>~/wiki-container</code> directory exists:<br>
<syntaxhighlight lang="bash">
mkdir -p ~/wiki-container
</syntaxhighlight><br>

<b>Step 2: Run Container with Volume Mount</b><br>
If your container isn’t already using a volume for <code>~/wiki-container</code>, stop and remove it, then restart with a volume mount:<br>
<syntaxhighlight lang="bash">
docker stop completenoobs_wiki
docker rm completenoobs_wiki
docker run -d -p 8080:80 \
-v ~/wiki-container:/export \
-v completenoobs_mysql:/var/lib/mysql \
-v completenoobs_images:/var/www/html/images \
--name completenoobs_wiki \
completenoobs/cnoobs-wiki:0.1
</syntaxhighlight><br>

<b>Step 3: Run Export Script in Container</b><br>
Access the container’s shell:<br>
<syntaxhighlight lang="bash">
docker exec -it completenoobs_wiki bash
</syntaxhighlight>
Inside the container, run the export script to create a dated XML file:<br>
<syntaxhighlight lang="bash">
DATE=$(date +%Y%m%d)
php /var/www/html/maintenance/run.php dumpBackup.php --full --output=file:/export/$DATE.xml
exit
</syntaxhighlight>
This writes the file (e.g., <code>20250901.xml</code>) to <code>/export</code> in the container, which maps to <code>~/wiki-container</code> on the host.<br><br>

<b>Step 4: Verify the File</b><br>
On the host, check for the XML file:<br>
<syntaxhighlight lang="bash">
ls ~/wiki-container
</syntaxhighlight>
You should see a file like <code>20250901.xml</code>.<br><br>

<b>Notes</b><br>
- If you encounter permission issues, ensure the container’s user has write access to <code>/export</code>:<br>
<syntaxhighlight lang="bash">
chmod -R 777 /export
</syntaxhighlight>
- The script must be run inside the container, as it requires MediaWiki’s environment and database access.<br>
- If your container uses a different volume setup, adjust the mount point accordingly.

</div>
</div>
<div class="toccolours mw-collapsible mw-collapsed">
Import MediaWiki XML File from Host Directory:
<div class="mw-collapsible-content">

To import a <code>wiki.xml</code> file from the host’s <code>~/wiki-container</code> directory into your MediaWiki instance running in a Docker container, use the <code>importDump.php</code> script inside the container. The <code>~/wiki-container</code> directory is mounted as <code>/export</code> in the container, allowing the container to read the file.<br><br>

<b>Step 1: Place the XML File</b><br>
On the host, move or copy the <code>wiki.xml</code> file to <code>~/wiki-container</code>:<br>
<syntaxhighlight lang="bash">
mv ~/Downloads/wiki.xml ~/wiki-container/
</syntaxhighlight>
Verify the file is present:<br>
<syntaxhighlight lang="bash">
ls ~/wiki-container
</syntaxhighlight><br>

<b>Step 2: Access the Container’s Shell</b><br>
Enter the container’s shell:<br>
<syntaxhighlight lang="bash">
docker exec -it completenoobs_wiki bash
</syntaxhighlight><br>

<b>Step 3: Run the Import Script</b><br>
Inside the container, import the <code>wiki.xml</code> file:<br>
Can check file is present in container with <code>ls /export/</code><br>
<syntaxhighlight lang="bash">
php /var/www/html/maintenance/run.php importDump.php /export/wiki.xml
</syntaxhighlight><br>
Note: This imports the XML content into the MediaWiki database. For large files, this may take time.<br><br>

<b>Step 4: Rebuild Wiki Indexes (Optional but Recommended)</b><br>
Rebuild the wiki’s indexes to ensure imported content is accessible:<br>
<syntaxhighlight lang="bash">
php /var/www/html/maintenance/run.php rebuildall.php
</syntaxhighlight><br>

<b>Step 5: Exit the Container</b><br>
Exit the container’s shell:<br>
<syntaxhighlight lang="bash">
exit
</syntaxhighlight><br>

<b>Step 6: Verify the Import</b><br>
Visit your wiki (e.g., <code>http://localhost:8080</code>) to check if the imported pages appear. If issues arise, check the container logs:<br>
<syntaxhighlight lang="bash">
docker logs completenoobs_wiki
</syntaxhighlight><br>

<b>Notes</b><br>
- Ensure the container has read access to <code>/export</code>. Fix permissions if needed:<br>
<syntaxhighlight lang="bash">
chmod -R 777 /export
</syntaxhighlight>
- If you want to overwrite existing pages, use the <code>--no-updates</code> flag with <code>importDump.php</code>.<br>
- If the container wasn’t started with <code>~/wiki-container</code> mounted as <code>/export</code>, restart it with:<br>
<syntaxhighlight lang="bash">
docker run -d -p 8080:80 -v ~/wiki-container:/export --name completenoobs_wiki completenoobs/cnoobs-wiki:0.1
</syntaxhighlight>

</div>
</div>

* Now visit http://localhost:8080 on your browser

* Due to (unknown) bug you might need to update the xml to download missing pages:
<code>docker exec -it completenoobs_wiki /var/www/html/check_updates.sh</code>

<div class="toccolours mw-collapsible mw-collapsed">
Change Admin Password:
<div class="mw-collapsible-content">

By default, the admin user's password is <code>AdminPass123!</code>. It's highly recommended to change this immediately. You can do this either through the wiki's web interface or directly in the Docker terminal.<br><br>

<b>Method 1: Change Password via Web Interface</b><br>
This is the easiest method. You can change your password directly from the wiki itself.<br>

1. Log in to your wiki with the default credentials: <code>admin</code> / <code>AdminPass123!</code>.<br>
2. Once logged in, click your username (<code>admin</code>) in the top-right corner of the page.<br>
3. From the drop-down menu, select <b>Preferences</b>.<br>
4. On the Preferences page, go to the <b>Password</b> tab.<br>
5. Enter the current password (<code>AdminPass123!</code>), then enter your new password twice.<br>
6. Click <b>Change password</b>.<br>

Your password is now changed, and you will need to use the new one for future logins.<br><br>

<b>Method 2: Change Password via Terminal (No-Email Reset)</b><br>
If you have forgotten the password or prefer to use the command line, you can reset it directly inside the Docker container using a MediaWiki maintenance script.<br>

1. <b>Access the container's shell</b> with the following command from your host machine:<br>
<syntaxhighlight lang="bash">
docker exec -it completenoobs_wiki bash
</syntaxhighlight>

2. Once inside the container, use the <code>changePassword.php</code> maintenance script to change the password. This is the modern, recommended way to run MediaWiki maintenance scripts.<br>
* Change <b>NEWPASSWORD</b> to your new password<br>
<syntaxhighlight lang="bash">
php /var/www/html/maintenance/run.php changePassword.php --user=admin --password=NEWPASSWORD
</syntaxhighlight>

3. Type <code>exit</code> to leave the container's shell.<br>

The admin password has now been reset. You can log in to your wiki with the new password.
</div>
</div>

===Remove container===

To completely remove the <code>completenoobs/cnoobs-wiki:0.1</code> container and image from your Ubuntu 24.04 system, follow these steps. You can also remove associated persistent storage volumes if they were created.<br><br>

<b>Step 1: Stop and Remove the Container</b><br>
If the container is running, stop it and then remove it.<br>
<syntaxhighlight lang="bash">
docker stop completenoobs_wiki
docker rm completenoobs_wiki
</syntaxhighlight>
Alternatively, stop and remove in one command:<br>
<syntaxhighlight lang="bash">
docker rm -f completenoobs_wiki
</syntaxhighlight><br>

<b>Step 2: Remove the Docker Image</b><br>
Remove the <code>completenoobs/cnoobs-wiki:0.1</code> image.<br>
<syntaxhighlight lang="bash">
docker rmi completenoobs/cnoobs-wiki:0.1
</syntaxhighlight>
Note: If the image is in use by other containers, remove those containers first or use <code>docker rmi -f completenoobs/cnoobs-wiki:0.1</code> to force removal (use with caution).<br><br>

<b>Step 3: Remove Persistent Storage Volumes (Optional)</b><br>
If you used persistent storage, remove the associated volumes to free up space.<br>
<syntaxhighlight lang="bash">
docker volume rm completenoobs_mysql completenoobs_images
</syntaxhighlight>
Note: Ensure no other containers are using these volumes, as this will delete all stored data.<br><br>

<b>Step 4: Verify Removal</b><br>
Check that the container, image, and volumes are removed.<br>
- List all containers (including stopped ones):<br>
<syntaxhighlight lang="bash">
docker ps -a
</syntaxhighlight>
- List all images:<br>
<syntaxhighlight lang="bash">
docker images
</syntaxhighlight>
- List all volumes:<br>
<syntaxhighlight lang="bash">
docker volume ls
</syntaxhighlight>
If any items remain, repeat the relevant removal commands or check for dependencies.

==Docker Compose container==

Ubuntu2404 Install Docker and Docker Compose

2025-09-01T21:13:29Z

AwesomO: /* Run container */

CompleteNoobs Docker Image Creation

2025-09-01T20:52:16Z

AwesomO: /* 3.2: Run the Container */

= Complete Noobs Docker Wiki Tutorial =
* [[Docker_Install_Guide| Docker install guide]]
==errors==
* This mainly works - just need to fix the extensions popular pages and contrubtion scores
* The XML updater requires more work - currently idea placeholder

== Prerequisites ==
* Ubuntu 24.04
* Docker installed and running
* Your user in docker group: <code>sudo usermod -aG docker $USER</code> (then logout/login)

== Step 2: Create All Files ==

=== 2.1: Dockerfile ===
<syntaxhighlight lang="bash">
nano Dockerfile
</syntaxhighlight>
Copy this exactly:

<syntaxhighlight lang="dockerfile">
FROM mediawiki:1.44
# Mediawiki 1.44 used over latest because can confirm extensions youtube and pagenotice works
# Install dependencies
RUN apt-get update && apt-get install -y \
mariadb-server \
python3 \
python3-requests \
python3-bs4 \
python3-pygments \
curl \
wget \
unzip \
nano \
git \
&& apt-get clean

# Copy scripts
COPY download_latest_xml.py /usr/src/download_latest_xml.py
COPY setup_wiki.sh /usr/src/setup_wiki.sh
COPY update_xml.sh /usr/src/update_xml.sh
COPY entrypoint.sh /entrypoint.sh

# Make executable
RUN chmod +x /usr/src/setup_wiki.sh /entrypoint.sh /usr/src/update_xml.sh

# Download XML
RUN python3 /usr/src/download_latest_xml.py

# Setup wiki
RUN /usr/src/setup_wiki.sh

EXPOSE 80
VOLUME /var/lib/mysql
VOLUME /var/www/html/images

ENTRYPOINT ["/entrypoint.sh"]
</syntaxhighlight>

=== 2.2: XML Download Script ===
<syntaxhighlight lang="bash">
nano download_latest_xml.py
</syntaxhighlight>

<syntaxhighlight lang="python">
#!/usr/bin/env python3
import os
import requests
from bs4 import BeautifulSoup
import re

BASE_URL = "https://xml.completenoobs.com/xmlDumps/"

def parse_date_from_dump(dump_name):
match = re.match(r'(\d{2})_(\d{2})_(\d{2})\.Noobs', dump_name)
if match:
day, month, year = match.groups()
year_int = int(year)
full_year = 2000 + year_int if year_int <= 49 else 1900 + year_int
return (full_year, int(month), int(day))
return (0, 0, 0)

def get_available_dumps():
try:
response = requests.get(BASE_URL, timeout=30)
response.raise_for_status()
soup = BeautifulSoup(response.text, 'html.parser')
dumps = [link.get('href').rstrip('/') for link in soup.find_all('a')
if re.match(r'\d{2}_\d{2}_\d{2}\.Noobs/$', link.get('href', ''))]
return sorted(dumps, key=parse_date_from_dump, reverse=True)
except Exception as e:
print(f"Error fetching dumps: {e}")
return []

def get_dump_files(dump):
try:
response = requests.get(f"{BASE_URL}{dump}/", timeout=30)
response.raise_for_status()
soup = BeautifulSoup(response.text, 'html.parser')
files = [link.get('href') for link in soup.find_all('a')
if link.get('href', '').endswith('.xml')]
return sorted(files, reverse=True)
except Exception as e:
print(f"Error fetching dump files: {e}")
return []

def download_file(url, filename):
try:
print(f"Downloading {filename}...")
response = requests.get(url, stream=True, timeout=60)
response.raise_for_status()

total_size = int(response.headers.get('content-length', 0))
downloaded = 0

with open(filename, 'wb') as f:
for chunk in response.iter_content(chunk_size=8192):
if chunk:
f.write(chunk)
downloaded += len(chunk)
if total_size > 0:
progress = (downloaded / total_size) * 100
print(f"\rProgress: {progress:.1f}%", end='', flush=True)
print()
return True
except Exception as e:
print(f"Error downloading {filename}: {e}")
return False

def main():
print("Fetching available XML dumps...")
dumps = get_available_dumps()

if not dumps:
print("No dumps found!")
exit(1)

newest_dump = dumps[0]
print(f"Latest dump: {newest_dump}")

files = get_dump_files(newest_dump)
if not files:
print("No XML files found in latest dump!")
exit(1)

newest_xml = files[0]
xml_url = f"{BASE_URL}{newest_dump}/{newest_xml}"
local_filename = "/tmp/completenoobs_dump.xml"

if download_file(xml_url, local_filename):
print(f"Successfully downloaded {newest_xml}")
with open("/tmp/dump_info.txt", "w") as f:
f.write(f"{newest_dump}/{newest_xml}")
else:
print("Failed to download XML dump!")
exit(1)

if __name__ == "__main__":
main()
</syntaxhighlight>

=== 2.3: Main Setup Script ===
<syntaxhighlight lang="bash">
nano setup_wiki.sh
</syntaxhighlight>

<syntaxhighlight lang="bash">
#!/bin/bash
set -e

echo "Setting up CompleteNoobs Wiki..."

# Initialize MariaDB
if [ ! -d "/var/lib/mysql/mysql" ]; then
mysql_install_db --user=mysql --datadir=/var/lib/mysql
fi

service mariadb start

# Wait for MariaDB
for i in {1..30}; do
if mysql -e "SELECT 1;" &>/dev/null; then
echo "MariaDB ready!"
break
fi
sleep 2
done

# Setup database
mysql -e "CREATE DATABASE IF NOT EXISTS completenoobs_wiki CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
mysql -e "CREATE USER IF NOT EXISTS 'wikiuser'@'127.0.0.1' IDENTIFIED BY 'wikipass';"
mysql -e "GRANT ALL PRIVILEGES ON completenoobs_wiki.* TO 'wikiuser'@'127.0.0.1';"
mysql -e "CREATE USER IF NOT EXISTS 'wikiuser'@'localhost' IDENTIFIED BY 'wikipass';"
mysql -e "GRANT ALL PRIVILEGES ON completenoobs_wiki.* TO 'wikiuser'@'localhost';"
mysql -e "FLUSH PRIVILEGES;"

# Install MediaWiki
cd /var/www/html
php maintenance/install.php \
--dbtype=mysql \
--dbserver=127.0.0.1 \
--dbname=completenoobs_wiki \
--dbuser=wikiuser \
--dbpass=wikipass \
--server="http://localhost:8080" \
--scriptpath="" \
--lang=en \
--pass=AdminPass123! \
"CompleteNoobs Wiki" \
"admin"

# Download and install extensions
cd extensions/
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/PageNotice --branch REL1_44 || echo "PageNotice download failed, continuing..."
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/YouTube --branch REL1_44 || echo "YouTube download failed, continuing..."
cd /var/www/html

# Configure LocalSettings.php
cat >> LocalSettings.php << 'EOF'
# Basic settings
$wgEnableUploads = true;
$wgUseImageMagick = true;
$wgImageMagickConvertCommand = "/usr/bin/convert";
$wgDefaultSkin = "vector-2022";
$wgAllowExternalImages = true;

# Debug (can be removed later)
$wgShowExceptionDetails = true;
$wgDebugLogFile = "/tmp/mediawiki-debug.log";

# PageNotice extension (if available)
if ( file_exists( "$IP/extensions/PageNotice/extension.json" ) ) {
wfLoadExtension( 'PageNotice' );
}

# YouTube extension (if available)
if ( file_exists( "$IP/extensions/YouTube/extension.json" ) ) {
wfLoadExtension( 'YouTube' );
}

# SyntaxHighlight (usually bundled)
if ( file_exists( "$IP/extensions/SyntaxHighlight_GeSHi/extension.json" ) ) {
wfLoadExtension( 'SyntaxHighlight_GeSHi' );
$wgPygmentizePath = '/usr/bin/pygmentize';
}
EOF

# Import XML dump if available
if [ -f "/tmp/completenoobs_dump.xml" ]; then
echo "Importing XML dump..."

if php maintenance/importDump.php --uploads < /tmp/completenoobs_dump.xml; then
echo "XML import completed!"
else
echo "XML import had warnings"
fi

# Basic maintenance
php maintenance/update.php --quick || echo "Update completed with warnings"
php maintenance/rebuildrecentchanges.php || echo "RecentChanges rebuilt with warnings"
php maintenance/initSiteStats.php || echo "SiteStats initialized with warnings"

if [ -f "/tmp/dump_info.txt" ]; then
echo "Import: $(cat /tmp/dump_info.txt)" > /var/www/html/.last_import
echo "Date: $(date)" >> /var/www/html/.last_import
fi
else
echo "No XML dump found - starting with empty wiki"
fi

# Copy update script to accessible location
cp /usr/src/update_xml.sh /var/www/html/update_xml.sh
chmod +x /var/www/html/update_xml.sh

# Create user-friendly update wrapper
cat > /var/www/html/check_updates.sh << 'UPDATE_WRAPPER_EOF'
#!/bin/bash
echo "=== CompleteNoobs Wiki Update Checker ==="
echo ""
echo "This tool checks for new content from the CompleteNoobs XML repository"
echo "and imports ONLY new pages, preserving all your local edits."
echo ""

/var/www/html/update_xml.sh
UPDATE_WRAPPER_EOF
chmod +x /var/www/html/check_updates.sh

# Create simple status script
cat > /var/www/html/check_status.sh << 'STATUS_EOF'
#!/bin/bash
cd /var/www/html
echo "=== Wiki Status ==="
echo "Pages: $(mysql --user=wikiuser --password=wikipass completenoobs_wiki -e "SELECT COUNT(*) FROM page;" -s -N 2>/dev/null || echo "Error")"
echo "Users: $(mysql --user=wikiuser --password=wikipass completenoobs_wiki -e "SELECT COUNT(*) FROM user WHERE user_id > 0;" -s -N 2>/dev/null || echo "Error")"
echo ""
echo "=== Extensions ==="
if [ -d "extensions/PageNotice" ]; then
echo "PageNotice: Installed"
else
echo "PageNotice: Not installed"
fi
if [ -d "extensions/YouTube" ]; then
echo "YouTube: Installed"
else
echo "YouTube: Not installed"
fi
if [ -d "extensions/ContributionScores" ]; then
echo "ContributionScores: Installed"
else
echo "ContributionScores: Not installed"
fi
echo ""
echo "=== Update System ==="
if [ -f ".last_import" ]; then
echo "Current version: $(grep 'Import:' .last_import | cut -d' ' -f2)"
echo "Import date: $(grep 'Date:' .last_import | cut -d' ' -f2-)"
else
echo "No version info available"
fi
echo ""
echo "To check for updates: docker exec -it completenoobs_wiki /var/www/html/check_updates.sh"
STATUS_EOF
chmod +x /var/www/html/check_status.sh

echo ""
echo "Setup completed!"
echo "Admin: admin / AdminPass123!"
echo "Update scripts installed:"
echo "- /var/www/html/check_updates.sh (user-friendly)"
echo "- /var/www/html/update_xml.sh (direct)"

# Final counts
PAGES=$(mysql --user=wikiuser --password=wikipass completenoobs_wiki -e "SELECT COUNT(*) FROM page;" -s -N 2>/dev/null || echo "0")
echo "Pages imported: $PAGES"

service mariadb stop
</syntaxhighlight>

=== 2.4: XML Update Script ===
<syntaxhighlight lang="bash">
nano update_xml.sh
</syntaxhighlight>

<syntaxhighlight lang="bash">
#!/bin/bash
set -e

echo "=== CompleteNoobs Wiki XML Updater ==="
echo "This will check for new and updated pages"
echo ""

# Function to check if running in container
check_environment() {
if [ ! -f "/var/www/html/LocalSettings.php" ]; then
echo "Error: This script must be run inside the wiki container"
exit 1
fi
}

# Function to get current XML version
get_current_version() {
if [ -f "/var/www/html/.last_import" ]; then
grep "Import:" /var/www/html/.last_import | cut -d' ' -f2
else
echo "none"
fi
}

# Function to check for updates
check_for_updates() {
python3 - << 'PYTHON_EOF'
import requests
from bs4 import BeautifulSoup
import re
import sys

BASE_URL = "https://xml.completenoobs.com/xmlDumps/"

def parse_date_from_dump(dump_name):
match = re.match(r'(\d{2})_(\d{2})_(\d{2})\.Noobs', dump_name)
if match:
day, month, year = match.groups()
year_int = int(year)
full_year = 2000 + year_int if year_int <= 49 else 1900 + year_int
return (full_year, int(month), int(day))
return (0, 0, 0)

def get_latest_dump():
try:
response = requests.get(BASE_URL, timeout=30)
response.raise_for_status()
soup = BeautifulSoup(response.text, 'html.parser')
dumps = [link.get('href').rstrip('/') for link in soup.find_all('a')
if re.match(r'\d{2}_\d{2}_\d{2}\.Noobs/$', link.get('href', ''))]
if dumps:
latest = sorted(dumps, key=parse_date_from_dump, reverse=True)[0]

# Get XML files from latest dump
response = requests.get(f"{BASE_URL}{latest}/", timeout=30)
response.raise_for_status()
soup = BeautifulSoup(response.text, 'html.parser')
files = [link.get('href') for link in soup.find_all('a')
if link.get('href', '').endswith('.xml')]

if files:
newest_xml = sorted(files, reverse=True)[0]
print(f"{latest}/{newest_xml}")
sys.exit(0)
except Exception as e:
print(f"ERROR: {e}", file=sys.stderr)
sys.exit(1)

print("ERROR: No dumps found", file=sys.stderr)
sys.exit(1)

get_latest_dump()
PYTHON_EOF
}

# Function to download new XML
download_xml() {
local dump_info="$1"
local dump_dir=$(echo "$dump_info" | cut -d'/' -f1)
local xml_file=$(echo "$dump_info" | cut -d'/' -f2)
local url="https://xml.completenoobs.com/xmlDumps/${dump_info}"

echo "Downloading: $xml_file"
echo "From: $dump_dir"
echo "URL: $url"

if wget -O /tmp/new_dump.xml "$url" --progress=bar:force 2>&1; then
echo "Download successful!"
return 0
else
echo "Download failed!"
return 1
fi
}

# Function to backup current database
backup_database() {
echo "Creating database backup..."
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
mysqldump --user=wikiuser --password=wikipass completenoobs_wiki > /tmp/wiki_backup_${TIMESTAMP}.sql
echo "Backup created: /tmp/wiki_backup_${TIMESTAMP}.sql"
}

# Function to analyze and import changes
analyze_and_import() {
echo "Analyzing differences between XML and local wiki..."

# Create analysis and import script for MediaWiki 1.44+
cat > /tmp/analyze_import.php << 'PHP_EOF'
<?php
require_once '/var/www/html/maintenance/Maintenance.php';

class AnalyzeAndImport extends Maintenance {
private $db;
private $new_pages = [];
private $changed_pages = [];
private $unchanged_pages = [];

public function __construct() {
parent::__construct();
$this->addDescription('Analyze and selectively import from XML dump');
}

public function execute() {
$this->db = new mysqli('127.0.0.1', 'wikiuser', 'wikipass', 'completenoobs_wiki');

// MediaWiki 1.35+ uses slots and content tables
// Get existing pages with their content
$query = "
SELECT p.page_title, p.page_id, c.content_address, c.content_sha1
FROM page p
JOIN revision r ON p.page_latest = r.rev_id
JOIN slots s ON r.rev_id = s.slot_revision_id
JOIN slot_roles sr ON s.slot_role_id = sr.role_id
JOIN content c ON s.slot_content_id = c.content_id
WHERE p.page_namespace = 0 AND sr.role_name = 'main'
";

$result = $this->db->query($query);
if (!$result) {
$this->error("Database query failed: " . $this->db->error);
return;
}

$existing = [];
while ($row = $result->fetch_assoc()) {
// Get actual text content
$text_content = $this->getTextContent($row['content_address']);
$existing[$row['page_title']] = [
'id' => $row['page_id'],
'content' => $text_content,
'sha1' => $row['content_sha1']
];
}

// Parse XML and compare
$xml = simplexml_load_file('/tmp/new_dump.xml');

foreach ($xml->page as $page) {
$title = str_replace(' ', '_', (string)$page->title);
$xml_content = (string)$page->revision->text;

if (!isset($existing[$title])) {
// New page
$this->new_pages[$title] = $xml_content;
} else {
// Compare content using SHA1 for efficiency
$xml_sha1 = sha1($xml_content);

if ($existing[$title]['sha1'] !== $xml_sha1) {
// Content is different
$this->changed_pages[$title] = [
'local' => $existing[$title]['content'],
'xml' => $xml_content,
'page_id' => $existing[$title]['id']
];
} else {
$this->unchanged_pages[] = $title;
}
}
}

// Display summary
$this->output("\n=== Update Analysis ===\n");
$this->output("New pages to import: " . count($this->new_pages) . "\n");
$this->output("Changed pages found: " . count($this->changed_pages) . "\n");
$this->output("Unchanged pages: " . count($this->unchanged_pages) . "\n");

// Save analysis for review
file_put_contents('/tmp/update_analysis.json', json_encode([
'new' => array_keys($this->new_pages),
'changed' => array_keys($this->changed_pages),
'unchanged' => $this->unchanged_pages
], JSON_PRETTY_PRINT));

// Show changed pages with preview (limit to first 20 for readability)
if (count($this->changed_pages) > 0) {
$this->output("\n=== Changed Pages ===\n");
$count = 0;
$total_changed = count($this->changed_pages);

foreach ($this->changed_pages as $title => $data) {
$count++;
if ($count <= 20) {
$this->output("\n$count. $title\n");

// Create a simple diff preview (first 300 chars)
$xml_preview = substr($data['xml'], 0, 100);

// Save full diff to file
$safe_title = preg_replace('/[^a-zA-Z0-9_-]/', '_', $title);
$diff_file = "/tmp/diff_${safe_title}.txt";
file_put_contents($diff_file, "=== FULL DIFF FOR: $title ===\n\n");
file_put_contents($diff_file, "--- LOCAL VERSION ---\n", FILE_APPEND);
file_put_contents($diff_file, $data['local'] . "\n\n", FILE_APPEND);
file_put_contents($diff_file, "--- XML VERSION ---\n", FILE_APPEND);
file_put_contents($diff_file, $data['xml'], FILE_APPEND);

$this->output(" Preview: " . $xml_preview . "...\n");
}
}

if ($total_changed > 20) {
$this->output("\n... and " . ($total_changed - 20) . " more changed pages.\n");
$this->output("All diff files saved to /tmp/diff_*.txt\n");
}
}

// Interactive selection
if (count($this->new_pages) > 0 || count($this->changed_pages) > 0) {
$this->output("\n=== Import Options ===\n");
$this->output("1. Import new pages only (preserve all local changes)\n");
$this->output("2. Import new pages + update ALL changed pages (overwrites local changes)\n");
$this->output("3. Selective import (choose which updates to apply)\n");
$this->output("4. Cancel (no changes)\n");

// Save state for import script WITHOUT the XML object
$import_data = [
'new_pages' => $this->new_pages,
'changed_pages' => $this->changed_pages,
'xml_file' => '/tmp/new_dump.xml' // Save path instead of object
];

file_put_contents('/tmp/import_data.ser', serialize($import_data));
} else {
$this->output("\nNo changes detected. Your wiki is up to date!\n");
}
}

private function getTextContent($address) {
// Handle different content storage formats in MW 1.35+
if (strpos($address, 'tt:') === 0) {
// Text table reference
$text_id = substr($address, 3);
$result = $this->db->query("SELECT old_text FROM text WHERE old_id = $text_id");
if ($row = $result->fetch_assoc()) {
return $row['old_text'];
}
} elseif (strpos($address, 'es:') === 0) {
// External storage - would need special handling
return "[External storage content]";
}
// Direct content
return $address;
}
}

$maintClass = AnalyzeAndImport::class;
require_once RUN_MAINTENANCE_IF_MAIN;
PHP_EOF

cd /var/www/html
php /tmp/analyze_import.php
}

# Function to perform selected import
perform_import() {
local choice=$1

cat > /tmp/do_import.php << 'PHP_EOF'
<?php
require_once '/var/www/html/maintenance/Maintenance.php';

class DoImport extends Maintenance {
public function __construct() {
parent::__construct();
$this->addOption('mode', 'Import mode', true, true);
}

public function execute() {
$mode = $this->getOption('mode');
$data = unserialize(file_get_contents('/tmp/import_data.ser'));

// Load XML file
$xml = simplexml_load_file($data['xml_file']);

$new_imported = 0;
$updated = 0;

// Import new pages (always for modes 1-3)
if ($mode != '4') {
foreach ($data['new_pages'] as $title => $content) {
$this->importPage($title, $content, $xml);
$new_imported++;
$this->output("Imported new page: $title\n");
}
}

// Handle changed pages based on mode
if ($mode == '2') {
// Update all changed pages
foreach ($data['changed_pages'] as $title => $info) {
$this->output("Updating: $title\n");
if ($this->reimportPage($title, $xml)) {
$updated++;
$this->output("Updated page: $title\n");
} else {
$this->output("Failed to update: $title\n");
}
}
} elseif ($mode == '3') {
// Selective update
$this->output("\n=== Selective Import Mode ===\n");
$this->output("For each changed page, choose:\n");
$this->output(" y = yes, update this page\n");
$this->output(" n = no, keep local version\n");
$this->output(" d = show diff file\n");
$this->output(" a = update all remaining pages\n");
$this->output(" s = skip all remaining pages\n\n");

$update_all = false;
$skip_all = false;

foreach ($data['changed_pages'] as $title => $info) {
if ($skip_all) {
$this->output("Skipped: $title\n");
continue;
}

if ($update_all) {
if ($this->reimportPage($title, $xml)) {
$updated++;
$this->output("Updated: $title\n");
}
continue;
}

$this->output("\nPage: $title\n");
$this->output("Action (y/n/d/a/s): ");
$handle = fopen("php://stdin", "r");
$line = trim(fgets($handle));

while ($line == 'd') {
// Show diff
$safe_title = preg_replace('/[^a-zA-Z0-9_-]/', '_', $title);
$diff_file = "/tmp/diff_${safe_title}.txt";
if (file_exists($diff_file)) {
system("head -50 $diff_file");
$this->output("\n[Showing first 50 lines - full file at $diff_file]\n");
}
$this->output("Action (y/n/a/s): ");
$line = trim(fgets($handle));
}

if ($line == 'a') {
$update_all = true;
if ($this->reimportPage($title, $xml)) {
$updated++;
$this->output("Updated: $title\n");
}
} elseif ($line == 's') {
$skip_all = true;
$this->output("Skipped: $title\n");
} elseif ($line == 'y') {
if ($this->reimportPage($title, $xml)) {
$updated++;
$this->output("Updated: $title\n");
} else {
$this->output("Failed to update: $title\n");
}
} else {
$this->output("Skipped: $title\n");
}
}
}

$this->output("\n=== Import Complete ===\n");
$this->output("New pages imported: $new_imported\n");
$this->output("Pages updated: $updated\n");
}

private function importPage($title, $content, $xml) {
// Create single page XML for import
$tempFile = '/tmp/single_page_' . md5($title) . '.xml';
$singlePage = new SimpleXMLElement('<?xml version="1.0" encoding="utf-8"?><mediawiki></mediawiki>');

if ($xml->siteinfo) {
$siteinfo = $singlePage->addChild('siteinfo');
foreach ($xml->siteinfo->children() as $child) {
$siteinfo->addChild($child->getName(), (string)$child);
}
}

// Find and add the page
foreach ($xml->page as $page) {
if (str_replace(' ', '_', (string)$page->title) == $title) {
$newPage = $singlePage->addChild('page');
foreach ($page->children() as $child) {
if ($child->getName() == 'revision') {
$revision = $newPage->addChild('revision');
foreach ($child->children() as $revChild) {
$revision->addChild($revChild->getName(), (string)$revChild);
}
} else {
$newPage->addChild($child->getName(), (string)$child);
}
}
break;
}
}

$singlePage->asXML($tempFile);
exec("php /var/www/html/maintenance/importDump.php < $tempFile 2>&1");
unlink($tempFile);
}

private function reimportPage($title, $xml) {
// For updating existing pages, delete then reimport
$db = new mysqli('127.0.0.1', 'wikiuser', 'wikipass', 'completenoobs_wiki');

// Delete the existing page
$safe_title = $db->real_escape_string(str_replace(' ', '_', $title));
$db->query("DELETE FROM page WHERE page_title = '$safe_title' AND page_namespace = 0");

$db->close();

// Now import the new version
foreach ($xml->page as $page) {
if (str_replace(' ', '_', (string)$page->title) == $title) {
$tempFile = '/tmp/update_page_' . md5($title) . '.xml';
$singlePage = new SimpleXMLElement('<?xml version="1.0" encoding="utf-8"?><mediawiki></mediawiki>');

if ($xml->siteinfo) {
$siteinfo = $singlePage->addChild('siteinfo');
foreach ($xml->siteinfo->children() as $child) {
$siteinfo->addChild($child->getName(), (string)$child);
}
}

$newPage = $singlePage->addChild('page');
foreach ($page->children() as $child) {
if ($child->getName() == 'revision') {
$revision = $newPage->addChild('revision');
foreach ($child->children() as $revChild) {
$revision->addChild($revChild->getName(), (string)$revChild);
}
} else {
$newPage->addChild($child->getName(), (string)$child);
}
}

$singlePage->asXML($tempFile);
$result = exec("php /var/www/html/maintenance/importDump.php < $tempFile 2>&1", $output, $return);
unlink($tempFile);

return ($return === 0);
}
}

return false;
}
}

$maintClass = DoImport::class;
require_once RUN_MAINTENANCE_IF_MAIN;
PHP_EOF

cd /var/www/html
php /tmp/do_import.php --mode="$choice"
}

# Main execution
main() {
check_environment

# Start MariaDB if not running
service mariadb status > /dev/null 2>&1 || service mariadb start

# Wait for MariaDB
for i in {1..30}; do
if mysql -e "SELECT 1;" &>/dev/null; then
break
fi
sleep 1
done

CURRENT=$(get_current_version)
echo "Current version: $CURRENT"
echo ""

echo "Checking for updates..."
LATEST=$(check_for_updates 2>/dev/null)
if [ $? -ne 0 ] || [ -z "$LATEST" ] || [[ "$LATEST" == *"ERROR"* ]]; then
echo "Failed to check for updates"
exit 1
fi

echo "Latest available: $LATEST"
echo ""

# Always proceed to analysis even if versions match
# (there might be content updates in the same version)
echo "Proceeding with content analysis..."
echo ""

# Backup database
backup_database

# Download new XML
if ! download_xml "$LATEST"; then
echo "Failed to download new XML"
exit 1
fi

# Analyze differences
analyze_and_import

# Check if there are changes to import
if [ -f "/tmp/import_data.ser" ]; then
echo ""
read -p "Choose option (1-4): " -n 1 -r
echo

if [[ $REPLY =~ ^[1-4]$ ]]; then
if [ "$REPLY" != "4" ]; then
perform_import "$REPLY"

# Update version info
echo "Import: $LATEST" > /var/www/html/.last_import
echo "Date: $(date)" >> /var/www/html/.last_import

# Rebuild indices
echo "Rebuilding indices..."
php maintenance/rebuildrecentchanges.php
php maintenance/initSiteStats.php
else
echo "Update cancelled"
fi
else
echo "Invalid option. Update cancelled"
fi
fi

# Clean up temp files
rm -f /tmp/import_data.ser /tmp/update_analysis.json /tmp/diff_*.txt /tmp/analyze_import.php /tmp/do_import.php 2>/dev/null

echo ""
echo "Done!"
}

# Run main function
main "$@"
</syntaxhighlight>

=== 2.5: Entrypoint Script ===
<syntaxhighlight lang="bash">
nano entrypoint.sh
</syntaxhighlight>

<syntaxhighlight lang="bash">
#!/bin/bash

echo "Starting CompleteNoobs Wiki..."

service mariadb start

# Wait for MariaDB
for i in {1..30}; do
if mysql -e "SELECT 1;" &>/dev/null; then
echo "MariaDB ready!"
break
fi
sleep 1
done

echo ""
echo "CompleteNoobs Wiki ready at: http://localhost:8080"
echo "Admin login: admin / AdminPass123!"
echo ""
echo "Features:"
echo "- Complete wiki content imported from XML"
echo "- License notices on all pages (via PageNotice)"
echo "- SyntaxHighlight for code blocks"
echo "- YouTube video embedding"
echo "- Contribution Scores special page"
echo "- XML update system (preserves local edits)"
echo ""
echo "To check for updates: docker exec -it completenoobs_wiki /var/www/html/check_updates.sh"
echo ""

apache2-foreground
</syntaxhighlight>

== Step 3: Build and Run ==

=== 3.1: Build the Image ===
<syntaxhighlight lang="bash">
docker build -t completenoobs/wiki:latest .
</syntaxhighlight>
This will take several minutes.

=== 3.2: Run the Container ===
<syntaxhighlight lang="bash">
docker run -d -p 8080:80 \
-v completenoobs_mysql:/var/lib/mysql \
-v completenoobs_images:/var/www/html/images \
--name completenoobs_wiki completenoobs/wiki:latest
</syntaxhighlight>

* NOTE: The above <code>docker run</code> command is for quick testing, if you want to be able to export your wiki's database to an XML file you can backup and share, please use method in expanding info box below.
<div class="toccolours mw-collapsible mw-collapsed">
If you want to be able to Export Your MediaWiki Database to Dated XML File - use this <code>docker run</code> method:
<div class="mw-collapsible-content">

To export your MediaWiki database to a dated XML file (e.g., <code>20250901.xml</code>) and save it to the host’s <code>~/wiki-container</code> directory, run the export script inside the Docker container and use a volume mount to write the file to the host.<br><br>

<b>Step 1: Create Host Directory</b><br>
On the host, ensure the <code>~/wiki-container</code> directory exists:<br>
<syntaxhighlight lang="bash">
mkdir -p ~/wiki-container
</syntaxhighlight><br>

<b>Step 2: Run Container with Volume Mount</b><br>
If your container isn’t already using a volume for <code>~/wiki-container</code>, stop and remove it, then restart with a volume mount:<br>
<syntaxhighlight lang="bash">
docker stop completenoobs_wiki
docker rm completenoobs_wiki
docker run -d -p 8080:80 \
-v ~/wiki-container:/export \
-v completenoobs_mysql:/var/lib/mysql \
-v completenoobs_images:/var/www/html/images \
--name completenoobs_wiki \
completenoobs/cnoobs-wiki:0.1
</syntaxhighlight><br>

<b>Step 3: Run Export Script in Container</b><br>
Access the container’s shell:<br>
<syntaxhighlight lang="bash">
docker exec -it completenoobs_wiki bash
</syntaxhighlight>
Inside the container, run the export script to create a dated XML file:<br>
<syntaxhighlight lang="bash">
DATE=$(date +%Y%m%d)
php /var/www/html/maintenance/run.php dumpBackup.php --full --output=file:/export/$DATE.xml
exit
</syntaxhighlight>
This writes the file (e.g., <code>20250901.xml</code>) to <code>/export</code> in the container, which maps to <code>~/wiki-container</code> on the host.<br><br>

<b>Step 4: Verify the File</b><br>
On the host, check for the XML file:<br>
<syntaxhighlight lang="bash">
ls ~/wiki-container
</syntaxhighlight>
You should see a file like <code>20250901.xml</code>.<br><br>

<b>Notes</b><br>
- If you encounter permission issues, ensure the container’s user has write access to <code>/export</code>:<br>
<syntaxhighlight lang="bash">
chmod -R 777 /export
</syntaxhighlight>
- The script must be run inside the container, as it requires MediaWiki’s environment and database access.<br>
- If your container uses a different volume setup, adjust the mount point accordingly.

</div>
</div>

== Step 4: Test Everything ==

=== 4.1: Check the Wiki ===
* Visit: http://localhost:8080
* You should see the PageNotice at the top
* Login with: admin / AdminPass123!

<div class="toccolours mw-collapsible mw-collapsed">
Change Admin Password:
<div class="mw-collapsible-content">

By default, the admin user's password is <code>AdminPass123!</code>. It's highly recommended to change this immediately. You can do this either through the wiki's web interface or directly in the Docker terminal.<br><br>

<b>Method 1: Change Password via Web Interface</b><br>
This is the easiest method. You can change your password directly from the wiki itself.<br>

1. Log in to your wiki with the default credentials: <code>admin</code> / <code>AdminPass123!</code>.<br>
2. Once logged in, click your username (<code>admin</code>) in the top-right corner of the page.<br>
3. From the drop-down menu, select <b>Preferences</b>.<br>
4. On the Preferences page, go to the <b>Password</b> tab.<br>
5. Enter the current password (<code>AdminPass123!</code>), then enter your new password twice.<br>
6. Click <b>Change password</b>.<br>

Your password is now changed, and you will need to use the new one for future logins.<br><br>

<b>Method 2: Change Password via Terminal (No-Email Reset)</b><br>
If you have forgotten the password or prefer to use the command line, you can reset it directly inside the Docker container using a MediaWiki maintenance script.<br>

1. <b>Access the container's shell</b> with the following command from your host machine:<br>
<syntaxhighlight lang="bash">
docker exec -it completenoobs_wiki bash
</syntaxhighlight>

2. Once inside the container, use the <code>changePassword.php</code> maintenance script to change the password. This is the modern, recommended way to run MediaWiki maintenance scripts.<br>
* Change <b>NEWPASSWORD</b> to your new password<br>
<syntaxhighlight lang="bash">
php /var/www/html/maintenance/run.php changePassword.php --user=admin --password=NEWPASSWORD
</syntaxhighlight>

3. Type <code>exit</code> to leave the container's shell.<br>

The admin password has now been reset. You can log in to your wiki with the new password.
</div>
</div>

=== 4.2: Test Extensions ===
* '''YouTube''': Edit any page, add <code><youtube>N9qYF9DZPdw</youtube></code>
* '''PageNotice''': Should already be visible at the top
* '''SyntaxHighlight''': Add code blocks with <nowiki><code><syntaxhighlight lang="python">code here</syntaxhighlight></code></nowiki>

=== 4.3: Check Status ===
<syntaxhighlight lang="bash">
docker exec completenoobs_wiki /var/www/html/check_status.sh
</syntaxhighlight>

== Step 5: XML Update Operations ==
*NOTE: update_xml.sh still needs alot of work, this just idea placeholder for now.
=== 5.1: Check for Updates (Interactive) ===
<syntaxhighlight lang="bash">
docker exec -it completenoobs_wiki /var/www/html/check_updates.sh
</syntaxhighlight>
This will:
* Check the CompleteNoobs XML repository for new dumps
* Compare with your current version
* Ask for confirmation before updating
* Import ONLY new pages (preserves your edits)
* Create a backup before making changes

=== 5.2: Force Update (Non-Interactive) ===
<syntaxhighlight lang="bash">
docker exec completenoobs_wiki bash -c "echo 'y' | /var/www/html/update_xml.sh"
</syntaxhighlight>

=== 5.3: Manual Update Process ===
<syntaxhighlight lang="bash">
# 1. Enter container
docker exec -it completenoobs_wiki bash

# 2. Check current version
cat /var/www/html/.last_import

# 3. Run update
/var/www/html/check_updates.sh

# 4. Exit container
exit
</syntaxhighlight>

== Step 6: Troubleshooting Commands ==
=== Access container shell: ===
<syntaxhighlight lang="bash">
docker exec -it completenoobs_wiki bash
</syntaxhighlight>

=== Edit configuration: ===
<syntaxhighlight lang="bash">
docker exec -it completenoobs_wiki nano /var/www/html/LocalSettings.php
</syntaxhighlight>

=== Check logs: ===
<syntaxhighlight lang="bash">
docker logs completenoobs_wiki
</syntaxhighlight>

=== View update logs: ===
<syntaxhighlight lang="bash">
docker exec completenoobs_wiki tail -f /tmp/mediawiki-debug.log
</syntaxhighlight>

=== Complete restart: ===
<syntaxhighlight lang="bash">
docker stop completenoobs_wiki
docker rm completenoobs_wiki
docker run -d -p 8080:80 \
-v completenoobs_mysql:/var/lib/mysql \
-v completenoobs_images:/var/www/html/images \
--name completenoobs_wiki completenoobs/wiki:latest
</syntaxhighlight>

== Expected Results ==
* Working wiki with imported CompleteNoobs content
* PageNotice visible at top of all pages
* All extensions functional
* Text editors (nano/vim) available in container
* Utility scripts for maintenance
* XML update system that preserves local edits

==need to add==
* way for user to backup there local custom wiki - xml exporter

Ubuntu2404 Install Docker and Docker Compose

2025-09-01T20:50:32Z

AwesomO: /* Run container */

=== Preparation ===

Before we begin, make sure you're logged in with a user account that has sudo privileges.

=== Update System Packages ===

Update your package list to ensure you have the latest versions of packages:

<source lang="bash">
sudo apt update && sudo apt upgrade -y
</source>

=== Install Docker Prerequisites ===

Install the necessary packages for Docker setup:

<source lang="bash">
sudo apt install -y apt-transport-https ca-certificates curl software-properties-common
</source>

=== Setup Docker Repository ===

* '''Add Docker's Official GPG Key''':

<source lang="bash">
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
</source>

* '''Add the Docker Repository''':

<source lang="bash">
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
</source>

=== Install Docker and Docker Compose ===

* '''Update Package List Again''':

<source lang="bash">
sudo apt update
</source>

* '''Install Docker Engine, CLI, Containerd, and Additional Tools''':

<source lang="bash">
sudo apt install -y docker-ce docker-ce-cli containerd.io python3-bs4 python3-requests docker-compose
</source>



=== Verify Installation ===

Check if Docker and Docker Compose are installed correctly:

<source lang="bash">
docker --version
docker-compose --version
</source>

=== Configure User Permissions ===

To run Docker commands without <code>sudo</code>, add your user to the <code>docker</code> group:

<source lang="bash">
sudo usermod -aG docker $USER
</source>

'''Note''': After adding your user to the docker group, you'll need to '''log out and log back in''' for the changes to take effect.
If you do not log out and back in, Or you do not add your $USER to the docker group, you will be required to use sudo in some cases. such as ..

<div class="toccolours mw-collapsible mw-collapsed">
a way to apply group changes without logging out and back in - tip:
<div class="mw-collapsible-content">
<pre>
exec sudo su -l $USER
</pre>

This command will replace your current shell with a new login shell for your user, which will have the updated group memberships. Both of these methods will apply the group changes immediately, allowing you to use LXD commands without having to log out and back in.

<b>Remember</b>, these changes only apply to the current terminal session. If you open a new terminal window, you might need to run the command again or log out and back in for the changes to take effect system-wide.
</div>
</div>

===If Installing Docker messed up your LXC/LXD Networking===
To resolve networking conflicts between Docker and LXC containers on Ubuntu 24.04, enable IP forwarding on the host system:
* Open the sysctl configuration file in your preferred editor
<code>sudo $EDITOR /etc/sysctl.conf</code>
* Uncomment or add the following line (around line 28):
<pre>net.ipv4.ip_forward=1</pre>
* Apply the updated configuration to enable IP forwarding:
<code>sysctl -p</code><br>
* Restart the system to ensure all changes take effect.

This should resolve the networking issue for LXC containers when Docker is installed.

==Install First Container/Image==

Download the completenoobs container image, mediawiki with the completenoobs xml installed.

<code>docker pull completenoobs/cnoobs-wiki:0.1</code>

===Run container===

* Quick Start
<code>docker run -d -p 8080:80 completenoobs/cnoobs-wiki:0.1</code>

* Quick Start with Persistent Storage
<pre>
docker run -d -p 8080:80 \
-v completenoobs_mysql:/var/lib/mysql \
-v completenoobs_images:/var/www/html/images \
--name completenoobs_wiki \
completenoobs/cnoobs-wiki:0.1
</pre>

* NOTE: The above <code>docker run</code> command is for quick testing, if you want to be able to export your wiki's database to an XML file you can backup and share, please use method in expanding info box below.
<div class="toccolours mw-collapsible mw-collapsed">
If you want to be able to Export Your MediaWiki Database to Dated XML File - use this <code>docker run</code> method:
<div class="mw-collapsible-content">

To export your MediaWiki database to a dated XML file (e.g., <code>20250901.xml</code>) and save it to the host’s <code>~/wiki-container</code> directory, run the export script inside the Docker container and use a volume mount to write the file to the host.<br><br>

<b>Step 1: Create Host Directory</b><br>
On the host, ensure the <code>~/wiki-container</code> directory exists:<br>
<syntaxhighlight lang="bash">
mkdir -p ~/wiki-container
</syntaxhighlight><br>

<b>Step 2: Run Container with Volume Mount</b><br>
If your container isn’t already using a volume for <code>~/wiki-container</code>, stop and remove it, then restart with a volume mount:<br>
<syntaxhighlight lang="bash">
docker stop completenoobs_wiki
docker rm completenoobs_wiki
docker run -d -p 8080:80 \
-v ~/wiki-container:/export \
-v completenoobs_mysql:/var/lib/mysql \
-v completenoobs_images:/var/www/html/images \
--name completenoobs_wiki \
completenoobs/cnoobs-wiki:0.1
</syntaxhighlight><br>

<b>Step 3: Run Export Script in Container</b><br>
Access the container’s shell:<br>
<syntaxhighlight lang="bash">
docker exec -it completenoobs_wiki bash
</syntaxhighlight>
Inside the container, run the export script to create a dated XML file:<br>
<syntaxhighlight lang="bash">
DATE=$(date +%Y%m%d)
php /var/www/html/maintenance/run.php dumpBackup.php --full --output=file:/export/$DATE.xml
exit
</syntaxhighlight>
This writes the file (e.g., <code>20250901.xml</code>) to <code>/export</code> in the container, which maps to <code>~/wiki-container</code> on the host.<br><br>

<b>Step 4: Verify the File</b><br>
On the host, check for the XML file:<br>
<syntaxhighlight lang="bash">
ls ~/wiki-container
</syntaxhighlight>
You should see a file like <code>20250901.xml</code>.<br><br>

<b>Notes</b><br>
- If you encounter permission issues, ensure the container’s user has write access to <code>/export</code>:<br>
<syntaxhighlight lang="bash">
chmod -R 777 /export
</syntaxhighlight>
- The script must be run inside the container, as it requires MediaWiki’s environment and database access.<br>
- If your container uses a different volume setup, adjust the mount point accordingly.

</div>
</div>

* Now visit http://localhost:8080 on your browser

* Due to (unknown) bug you might need to update the xml to download missing pages:
<code>docker exec -it completenoobs_wiki /var/www/html/check_updates.sh</code>

<div class="toccolours mw-collapsible mw-collapsed">
Change Admin Password:
<div class="mw-collapsible-content">

By default, the admin user's password is <code>AdminPass123!</code>. It's highly recommended to change this immediately. You can do this either through the wiki's web interface or directly in the Docker terminal.<br><br>

<b>Method 1: Change Password via Web Interface</b><br>
This is the easiest method. You can change your password directly from the wiki itself.<br>

1. Log in to your wiki with the default credentials: <code>admin</code> / <code>AdminPass123!</code>.<br>
2. Once logged in, click your username (<code>admin</code>) in the top-right corner of the page.<br>
3. From the drop-down menu, select <b>Preferences</b>.<br>
4. On the Preferences page, go to the <b>Password</b> tab.<br>
5. Enter the current password (<code>AdminPass123!</code>), then enter your new password twice.<br>
6. Click <b>Change password</b>.<br>

Your password is now changed, and you will need to use the new one for future logins.<br><br>

<b>Method 2: Change Password via Terminal (No-Email Reset)</b><br>
If you have forgotten the password or prefer to use the command line, you can reset it directly inside the Docker container using a MediaWiki maintenance script.<br>

1. <b>Access the container's shell</b> with the following command from your host machine:<br>
<syntaxhighlight lang="bash">
docker exec -it completenoobs_wiki bash
</syntaxhighlight>

2. Once inside the container, use the <code>changePassword.php</code> maintenance script to change the password. This is the modern, recommended way to run MediaWiki maintenance scripts.<br>
* Change <b>NEWPASSWORD</b> to your new password<br>
<syntaxhighlight lang="bash">
php /var/www/html/maintenance/run.php changePassword.php --user=admin --password=NEWPASSWORD
</syntaxhighlight>

3. Type <code>exit</code> to leave the container's shell.<br>

The admin password has now been reset. You can log in to your wiki with the new password.
</div>
</div>

===Remove container===

To completely remove the <code>completenoobs/cnoobs-wiki:0.1</code> container and image from your Ubuntu 24.04 system, follow these steps. You can also remove associated persistent storage volumes if they were created.<br><br>

<b>Step 1: Stop and Remove the Container</b><br>
If the container is running, stop it and then remove it.<br>
<syntaxhighlight lang="bash">
docker stop completenoobs_wiki
docker rm completenoobs_wiki
</syntaxhighlight>
Alternatively, stop and remove in one command:<br>
<syntaxhighlight lang="bash">
docker rm -f completenoobs_wiki
</syntaxhighlight><br>

<b>Step 2: Remove the Docker Image</b><br>
Remove the <code>completenoobs/cnoobs-wiki:0.1</code> image.<br>
<syntaxhighlight lang="bash">
docker rmi completenoobs/cnoobs-wiki:0.1
</syntaxhighlight>
Note: If the image is in use by other containers, remove those containers first or use <code>docker rmi -f completenoobs/cnoobs-wiki:0.1</code> to force removal (use with caution).<br><br>

<b>Step 3: Remove Persistent Storage Volumes (Optional)</b><br>
If you used persistent storage, remove the associated volumes to free up space.<br>
<syntaxhighlight lang="bash">
docker volume rm completenoobs_mysql completenoobs_images
</syntaxhighlight>
Note: Ensure no other containers are using these volumes, as this will delete all stored data.<br><br>

<b>Step 4: Verify Removal</b><br>
Check that the container, image, and volumes are removed.<br>
- List all containers (including stopped ones):<br>
<syntaxhighlight lang="bash">
docker ps -a
</syntaxhighlight>
- List all images:<br>
<syntaxhighlight lang="bash">
docker images
</syntaxhighlight>
- List all volumes:<br>
<syntaxhighlight lang="bash">
docker volume ls
</syntaxhighlight>
If any items remain, repeat the relevant removal commands or check for dependencies.

Docker Mediawiki Local Install

2025-09-01T20:35:47Z

AwesomO: /* Step 2: Create a Docker Compose File */

= Setting Up a Plain MediaWiki Instance with Docker on Ubuntu 24.04 =

This guide provides a simple, step-by-step process to set up a basic MediaWiki instance locally using Docker and Docker Compose on Ubuntu 24.04.

It is designed for beginners and assumes you have Docker and Docker Compose installed (see [[Docker_Install_Guide]] for setup details).

The setup includes MediaWiki with a MariaDB database, running in Docker containers.

== Prerequisites ==
* Ubuntu 24.04
* Docker and Docker Compose installed
* Basic familiarity with terminal commands
* Internet connection for pulling Docker images

== Step 1: Create a Project Directory ==
Create a dedicated directory to organize your MediaWiki setup files.
<br>
<code>mkdir mediawiki-docker</code><br>
<code>cd mediawiki-docker</code>

== Step 2: Create a Docker Compose File ==
Create a '''docker-compose.yml''' file to define the MediaWiki and MariaDB services.

<code>nano docker-compose.yml</code>

Paste the following configuration into <code>docker-compose.yml</code>:

<pre>
version: '3.8'
services:
mediawiki:
image: mediawiki:1.41
ports:
- "8080:80"
depends_on:
database:
condition: service_healthy
volumes: # will uncomment line below after init setup of wiki
# - ./LocalSettings.php:/var/www/html/LocalSettings.php:ro
environment:
- MEDIAWIKI_DB_HOST=database
- MEDIAWIKI_DB_USER=wikiuser
- MEDIAWIKI_DB_PASSWORD=securepassword
- MEDIAWIKI_DB_NAME=mediawiki
database:
image: mariadb:10.11
environment:
- MARIADB_ROOT_PASSWORD=securepassword
- MARIADB_DATABASE=mediawiki
- MARIADB_USER=wikiuser
- MARIADB_PASSWORD=securepassword
- MARIADB_AUTO_UPGRADE=1
volumes:
- db_data:/var/lib/mysql
healthcheck:
test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
interval: 10s
timeout: 5s
retries: 5
mem_limit: 512m
volumes:
db_data:

</pre>

Save and exit (`Ctrl+O`, `Enter`, `Ctrl+X`).

'''Explanation:'''
* The mediawiki service uses MediaWiki 1.41 for stability.
* `database` service uses the MariaDB image for the database.
* Port `8080` maps to MediaWiki's web server port `80`.
* Environment variables set up the database connection.
* A volume persists MariaDB data.
* `LocalSettings.php` will be mounted later after setup.

== Step 3: Start the Containers ==
Run the following command to start the MediaWiki and MariaDB containers:

<code>docker-compose up -d</code>

* `-d` runs containers in the background.
* This pulls the MediaWiki and MariaDB images and starts the services.

== Step 4: Verify Containers Are Running ==
Check that both containers are running:

<code>docker ps</code>

You should see two containers: one for `mediawiki` and one for `mariadb`.

== Step 5: Access the MediaWiki Setup Page ==
Open a web browser and navigate to:

http://localhost:8080

You should see the MediaWiki setup page. If not, ensure containers are running and port `8080` is not blocked.

== Step 6: Complete the MediaWiki Web Installer ==
Follow the on-screen instructions in the browser:
* Select your language and click "Continue."
* Accept the defaults for database settings, these details can be found in your '''docker-compose.yml''' file.
** host: '''database''' - change from default '''localhost'''
** user: '''wikiuser''' - change from default '''root'''
** password: '''securepassword'''
** database name: '''mediawiki''' - change from default '''my_wiki'''
* Set up an admin user and password for your wiki.
* Complete the installation. At the end, MediaWiki generates a '''LocalSettings.php''' file.

== Step 7: Download and Place LocalSettings.php ==
The installer prompts you to download `LocalSettings.php`. Save it to your `mediawiki-docker` directory:

<code>mv ~/Downloads/LocalSettings.php ~/mediawiki-docker/</code>

Ensure the file is named exactly '''LocalSettings.php'''.<br>
The Docker Compose configuration mounts this file into the MediaWiki container.

== Step 8: Restart Containers ==
Restart the containers to apply '''LocalSettings.php''':

* Turn off container
<code>docker-compose down</code>

* Edit '''docker-compose.yml''' and uncomment the lines
<pre>
# volumes: # will uncomment these 2 lines after init setup of wiki
# - ./LocalSettings.php:/var/www/html/LocalSettings.php:ro
</pre>

<pre>
version: '3.8'
services:
mediawiki:
image: mediawiki:1.41
ports:
- "8080:80"
depends_on:
database:
condition: service_healthy
volumes: # will uncomment these 2 lines after init setup of wiki
- ./LocalSettings.php:/var/www/html/LocalSettings.php:ro
environment:
- MEDIAWIKI_DB_HOST=database
- MEDIAWIKI_DB_USER=wikiuser
- MEDIAWIKI_DB_PASSWORD=securepassword
- MEDIAWIKI_DB_NAME=mediawiki
database:
image: mariadb:10.11
environment:
- MARIADB_ROOT_PASSWORD=securepassword
- MARIADB_DATABASE=mediawiki
- MARIADB_USER=wikiuser
- MARIADB_PASSWORD=securepassword
- MARIADB_AUTO_UPGRADE=1
volumes:
- db_data:/var/lib/mysql
healthcheck:
test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
interval: 10s
timeout: 5s
retries: 5
mem_limit: 512m
volumes:
db_data:

</pre>

* start container
<code>docker-compose up -d</code>

== Step 9: Access Your Wiki ==
Visit `http://localhost:8080` again. You should now see your MediaWiki instance. Log in with the admin credentials you set during installation.

== Step 10: Basic Usage ==
* Create and edit pages using the MediaWiki interface.
* Access the wiki at `http://localhost:8080`.
* Manage users and settings via the admin account.

== Stopping and Removing Containers ==
To stop the containers:

<code>docker-compose stop</code>

To stop and remove containers (data persists in the `db_data` volume):

<code>docker-compose down</code>

To remove all data (including the database), also delete the volume:

<code>docker-compose down -v</code>

== Network Configuration ==

By default, your wiki might only be accessible from the host machine where Docker is running, using <code>localhost</code> or <code>127.0.0.1</code>. However, if you want others on your network to access your wiki, you need to make some adjustments.

'''Current Setup:''' The computer running Docker Compose has an IP address of <code>192.168.0.44</code>.

* You can find the IP address of your computer running Docker using the command:
<code>ip addr</code><br>
<div class="toccolours mw-collapsible mw-collapsed">
OutPut from <code>ip addr</code>
<div class="mw-collapsible-content">
<pre>
noob@noob-HP-EliteDesk-800-G1-DM:~$ ip addr
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
inet 127.0.0.1/8 scope host lo
valid_lft forever preferred_lft forever
inet6 ::1/128 scope host noprefixroute
valid_lft forever preferred_lft forever
2: eno1: <NO-CARRIER,BROADCAST,MULTICAST,UP> mtu 1500 qdisc fq_codel state DOWN group default qlen 1000
link/ether 8c:dc:d4:3d:93:49 brd ff:ff:ff:ff:ff:ff
altname enp0s25
3: wlxe8de27142be2: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000
link/ether e8:de:27:14:2b:e2 brd ff:ff:ff:ff:ff:ff
inet 192.168.0.44/24 brd 192.168.0.255 scope global dynamic noprefixroute wlxe8de27142be2
valid_lft 86357sec preferred_lft 86357sec
inet6 fe80::afbe:cc73:73a2:fcdf/64 scope link noprefixroute
valid_lft forever preferred_lft forever
</pre>
</div>
</div>

My IP is <code>192.168.0.44</code>

If someone from another computer on the network tries to visit <code>192.168.0.44:8080</code>, they might encounter a "cannot connect" error. This happens because MediaWiki, by default, redirects to <code>127.0.0.1:8080</code>, which is only accessible from the host machine itself.

'''Solution:''' To allow access from other devices on the same network, you need to:

* '''Edit the <code>LocalSettings.php</code> File:''' This isn't done inside the Docker container but rather in the directory where your <code>docker-compose.yml</code> file is located (~/mediawiki-docker/LocalSettings.php). Here, you need to change the server URL configuration.

* '''Modify URL Configuration:''' On lines 34-35 of <code>LocalSettings.php</code>, you'll find the following:

=== Allowing Access from Other Network Devices ===
Edit <code>LocalSettings.php</code> in the Docker Compose directory to change the server URL:
* Default - around line 33
<source lang="php">
## The protocol and server name to use in fully-qualified URLs
$wgServer = 'http://127.0.0.1:8080';
</source>
*Changed
<source lang="php">
## The protocol and server name to use in fully-qualified URLs
$wgServer = 'http://192.168.0.44:8080';
</source>

* Restart Docker to apply changes:

<source lang="bash">
docker-compose restart
</source>

This allows access to your wiki from other devices on the network using <code>192.168.0.44:8080</code>.
This adjustment tells MediaWiki to use the network IP of the host (<code>192.168.0.44</code>) instead of the local loopback (<code>127.0.0.1</code>), allowing other devices on the network to access the wiki through <code>192.168.0.44:8080</code>. Even after this change, <code>localhost:8080</code> or <code>127.0.0.1:8080</code> will still work on the host machine, but now the wiki is also accessible via the network IP from other devices.

== Troubleshooting ==
* '''Cannot access localhost:8080''': Check `docker ps` to ensure containers are running. Verify port `8080` is not used by another service (`sudo netstat -tuln | grep 8080`).
* '''Database connection error''': Ensure environment variables in `docker-compose.yml` match the installer settings.
* '''LocalSettings.php not found''': Confirm the file is in the `mediawiki-docker` directory and named correctly.

== Notes ==
* The database data is stored in a Docker volume (`db_data`) and persists between container restarts.
* To customize MediaWiki, edit `LocalSettings.php` and restart containers.
* For production, secure `MYSQL_ROOT_PASSWORD` and `MEDIAWIKI_DB_PASSWORD` with stronger values.

== References ==
* [[Docker_Install_Guide]]
* [https://hub.docker.com/_/mediawiki Official MediaWiki Docker Image]
* [https://hub.docker.com/_/mariadb Official MariaDB Docker Image]
* [https://www.mediawiki.org/wiki/Manual:Installing_MediaWiki MediaWiki Installation Guide]

CompleteNoobs Docker Image Creation

2025-09-01T20:20:28Z

AwesomO: /* Expected Results */

= Complete Noobs Docker Wiki Tutorial =
* [[Docker_Install_Guide| Docker install guide]]
==errors==
* This mainly works - just need to fix the extensions popular pages and contrubtion scores
* The XML updater requires more work - currently idea placeholder

== Prerequisites ==
* Ubuntu 24.04
* Docker installed and running
* Your user in docker group: <code>sudo usermod -aG docker $USER</code> (then logout/login)

== Step 2: Create All Files ==

=== 2.1: Dockerfile ===
<syntaxhighlight lang="bash">
nano Dockerfile
</syntaxhighlight>
Copy this exactly:

<syntaxhighlight lang="dockerfile">
FROM mediawiki:1.44
# Mediawiki 1.44 used over latest because can confirm extensions youtube and pagenotice works
# Install dependencies
RUN apt-get update && apt-get install -y \
mariadb-server \
python3 \
python3-requests \
python3-bs4 \
python3-pygments \
curl \
wget \
unzip \
nano \
git \
&& apt-get clean

# Copy scripts
COPY download_latest_xml.py /usr/src/download_latest_xml.py
COPY setup_wiki.sh /usr/src/setup_wiki.sh
COPY update_xml.sh /usr/src/update_xml.sh
COPY entrypoint.sh /entrypoint.sh

# Make executable
RUN chmod +x /usr/src/setup_wiki.sh /entrypoint.sh /usr/src/update_xml.sh

# Download XML
RUN python3 /usr/src/download_latest_xml.py

# Setup wiki
RUN /usr/src/setup_wiki.sh

EXPOSE 80
VOLUME /var/lib/mysql
VOLUME /var/www/html/images

ENTRYPOINT ["/entrypoint.sh"]
</syntaxhighlight>

=== 2.2: XML Download Script ===
<syntaxhighlight lang="bash">
nano download_latest_xml.py
</syntaxhighlight>

<syntaxhighlight lang="python">
#!/usr/bin/env python3
import os
import requests
from bs4 import BeautifulSoup
import re

BASE_URL = "https://xml.completenoobs.com/xmlDumps/"

def parse_date_from_dump(dump_name):
match = re.match(r'(\d{2})_(\d{2})_(\d{2})\.Noobs', dump_name)
if match:
day, month, year = match.groups()
year_int = int(year)
full_year = 2000 + year_int if year_int <= 49 else 1900 + year_int
return (full_year, int(month), int(day))
return (0, 0, 0)

def get_available_dumps():
try:
response = requests.get(BASE_URL, timeout=30)
response.raise_for_status()
soup = BeautifulSoup(response.text, 'html.parser')
dumps = [link.get('href').rstrip('/') for link in soup.find_all('a')
if re.match(r'\d{2}_\d{2}_\d{2}\.Noobs/$', link.get('href', ''))]
return sorted(dumps, key=parse_date_from_dump, reverse=True)
except Exception as e:
print(f"Error fetching dumps: {e}")
return []

def get_dump_files(dump):
try:
response = requests.get(f"{BASE_URL}{dump}/", timeout=30)
response.raise_for_status()
soup = BeautifulSoup(response.text, 'html.parser')
files = [link.get('href') for link in soup.find_all('a')
if link.get('href', '').endswith('.xml')]
return sorted(files, reverse=True)
except Exception as e:
print(f"Error fetching dump files: {e}")
return []

def download_file(url, filename):
try:
print(f"Downloading {filename}...")
response = requests.get(url, stream=True, timeout=60)
response.raise_for_status()

total_size = int(response.headers.get('content-length', 0))
downloaded = 0

with open(filename, 'wb') as f:
for chunk in response.iter_content(chunk_size=8192):
if chunk:
f.write(chunk)
downloaded += len(chunk)
if total_size > 0:
progress = (downloaded / total_size) * 100
print(f"\rProgress: {progress:.1f}%", end='', flush=True)
print()
return True
except Exception as e:
print(f"Error downloading {filename}: {e}")
return False

def main():
print("Fetching available XML dumps...")
dumps = get_available_dumps()

if not dumps:
print("No dumps found!")
exit(1)

newest_dump = dumps[0]
print(f"Latest dump: {newest_dump}")

files = get_dump_files(newest_dump)
if not files:
print("No XML files found in latest dump!")
exit(1)

newest_xml = files[0]
xml_url = f"{BASE_URL}{newest_dump}/{newest_xml}"
local_filename = "/tmp/completenoobs_dump.xml"

if download_file(xml_url, local_filename):
print(f"Successfully downloaded {newest_xml}")
with open("/tmp/dump_info.txt", "w") as f:
f.write(f"{newest_dump}/{newest_xml}")
else:
print("Failed to download XML dump!")
exit(1)

if __name__ == "__main__":
main()
</syntaxhighlight>

=== 2.3: Main Setup Script ===
<syntaxhighlight lang="bash">
nano setup_wiki.sh
</syntaxhighlight>

<syntaxhighlight lang="bash">
#!/bin/bash
set -e

echo "Setting up CompleteNoobs Wiki..."

# Initialize MariaDB
if [ ! -d "/var/lib/mysql/mysql" ]; then
mysql_install_db --user=mysql --datadir=/var/lib/mysql
fi

service mariadb start

# Wait for MariaDB
for i in {1..30}; do
if mysql -e "SELECT 1;" &>/dev/null; then
echo "MariaDB ready!"
break
fi
sleep 2
done

# Setup database
mysql -e "CREATE DATABASE IF NOT EXISTS completenoobs_wiki CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
mysql -e "CREATE USER IF NOT EXISTS 'wikiuser'@'127.0.0.1' IDENTIFIED BY 'wikipass';"
mysql -e "GRANT ALL PRIVILEGES ON completenoobs_wiki.* TO 'wikiuser'@'127.0.0.1';"
mysql -e "CREATE USER IF NOT EXISTS 'wikiuser'@'localhost' IDENTIFIED BY 'wikipass';"
mysql -e "GRANT ALL PRIVILEGES ON completenoobs_wiki.* TO 'wikiuser'@'localhost';"
mysql -e "FLUSH PRIVILEGES;"

# Install MediaWiki
cd /var/www/html
php maintenance/install.php \
--dbtype=mysql \
--dbserver=127.0.0.1 \
--dbname=completenoobs_wiki \
--dbuser=wikiuser \
--dbpass=wikipass \
--server="http://localhost:8080" \
--scriptpath="" \
--lang=en \
--pass=AdminPass123! \
"CompleteNoobs Wiki" \
"admin"

# Download and install extensions
cd extensions/
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/PageNotice --branch REL1_44 || echo "PageNotice download failed, continuing..."
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/YouTube --branch REL1_44 || echo "YouTube download failed, continuing..."
cd /var/www/html

# Configure LocalSettings.php
cat >> LocalSettings.php << 'EOF'
# Basic settings
$wgEnableUploads = true;
$wgUseImageMagick = true;
$wgImageMagickConvertCommand = "/usr/bin/convert";
$wgDefaultSkin = "vector-2022";
$wgAllowExternalImages = true;

# Debug (can be removed later)
$wgShowExceptionDetails = true;
$wgDebugLogFile = "/tmp/mediawiki-debug.log";

# PageNotice extension (if available)
if ( file_exists( "$IP/extensions/PageNotice/extension.json" ) ) {
wfLoadExtension( 'PageNotice' );
}

# YouTube extension (if available)
if ( file_exists( "$IP/extensions/YouTube/extension.json" ) ) {
wfLoadExtension( 'YouTube' );
}

# SyntaxHighlight (usually bundled)
if ( file_exists( "$IP/extensions/SyntaxHighlight_GeSHi/extension.json" ) ) {
wfLoadExtension( 'SyntaxHighlight_GeSHi' );
$wgPygmentizePath = '/usr/bin/pygmentize';
}
EOF

# Import XML dump if available
if [ -f "/tmp/completenoobs_dump.xml" ]; then
echo "Importing XML dump..."

if php maintenance/importDump.php --uploads < /tmp/completenoobs_dump.xml; then
echo "XML import completed!"
else
echo "XML import had warnings"
fi

# Basic maintenance
php maintenance/update.php --quick || echo "Update completed with warnings"
php maintenance/rebuildrecentchanges.php || echo "RecentChanges rebuilt with warnings"
php maintenance/initSiteStats.php || echo "SiteStats initialized with warnings"

if [ -f "/tmp/dump_info.txt" ]; then
echo "Import: $(cat /tmp/dump_info.txt)" > /var/www/html/.last_import
echo "Date: $(date)" >> /var/www/html/.last_import
fi
else
echo "No XML dump found - starting with empty wiki"
fi

# Copy update script to accessible location
cp /usr/src/update_xml.sh /var/www/html/update_xml.sh
chmod +x /var/www/html/update_xml.sh

# Create user-friendly update wrapper
cat > /var/www/html/check_updates.sh << 'UPDATE_WRAPPER_EOF'
#!/bin/bash
echo "=== CompleteNoobs Wiki Update Checker ==="
echo ""
echo "This tool checks for new content from the CompleteNoobs XML repository"
echo "and imports ONLY new pages, preserving all your local edits."
echo ""

/var/www/html/update_xml.sh
UPDATE_WRAPPER_EOF
chmod +x /var/www/html/check_updates.sh

# Create simple status script
cat > /var/www/html/check_status.sh << 'STATUS_EOF'
#!/bin/bash
cd /var/www/html
echo "=== Wiki Status ==="
echo "Pages: $(mysql --user=wikiuser --password=wikipass completenoobs_wiki -e "SELECT COUNT(*) FROM page;" -s -N 2>/dev/null || echo "Error")"
echo "Users: $(mysql --user=wikiuser --password=wikipass completenoobs_wiki -e "SELECT COUNT(*) FROM user WHERE user_id > 0;" -s -N 2>/dev/null || echo "Error")"
echo ""
echo "=== Extensions ==="
if [ -d "extensions/PageNotice" ]; then
echo "PageNotice: Installed"
else
echo "PageNotice: Not installed"
fi
if [ -d "extensions/YouTube" ]; then
echo "YouTube: Installed"
else
echo "YouTube: Not installed"
fi
if [ -d "extensions/ContributionScores" ]; then
echo "ContributionScores: Installed"
else
echo "ContributionScores: Not installed"
fi
echo ""
echo "=== Update System ==="
if [ -f ".last_import" ]; then
echo "Current version: $(grep 'Import:' .last_import | cut -d' ' -f2)"
echo "Import date: $(grep 'Date:' .last_import | cut -d' ' -f2-)"
else
echo "No version info available"
fi
echo ""
echo "To check for updates: docker exec -it completenoobs_wiki /var/www/html/check_updates.sh"
STATUS_EOF
chmod +x /var/www/html/check_status.sh

echo ""
echo "Setup completed!"
echo "Admin: admin / AdminPass123!"
echo "Update scripts installed:"
echo "- /var/www/html/check_updates.sh (user-friendly)"
echo "- /var/www/html/update_xml.sh (direct)"

# Final counts
PAGES=$(mysql --user=wikiuser --password=wikipass completenoobs_wiki -e "SELECT COUNT(*) FROM page;" -s -N 2>/dev/null || echo "0")
echo "Pages imported: $PAGES"

service mariadb stop
</syntaxhighlight>

=== 2.4: XML Update Script ===
<syntaxhighlight lang="bash">
nano update_xml.sh
</syntaxhighlight>

<syntaxhighlight lang="bash">
#!/bin/bash
set -e

echo "=== CompleteNoobs Wiki XML Updater ==="
echo "This will check for new and updated pages"
echo ""

# Function to check if running in container
check_environment() {
if [ ! -f "/var/www/html/LocalSettings.php" ]; then
echo "Error: This script must be run inside the wiki container"
exit 1
fi
}

# Function to get current XML version
get_current_version() {
if [ -f "/var/www/html/.last_import" ]; then
grep "Import:" /var/www/html/.last_import | cut -d' ' -f2
else
echo "none"
fi
}

# Function to check for updates
check_for_updates() {
python3 - << 'PYTHON_EOF'
import requests
from bs4 import BeautifulSoup
import re
import sys

BASE_URL = "https://xml.completenoobs.com/xmlDumps/"

def parse_date_from_dump(dump_name):
match = re.match(r'(\d{2})_(\d{2})_(\d{2})\.Noobs', dump_name)
if match:
day, month, year = match.groups()
year_int = int(year)
full_year = 2000 + year_int if year_int <= 49 else 1900 + year_int
return (full_year, int(month), int(day))
return (0, 0, 0)

def get_latest_dump():
try:
response = requests.get(BASE_URL, timeout=30)
response.raise_for_status()
soup = BeautifulSoup(response.text, 'html.parser')
dumps = [link.get('href').rstrip('/') for link in soup.find_all('a')
if re.match(r'\d{2}_\d{2}_\d{2}\.Noobs/$', link.get('href', ''))]
if dumps:
latest = sorted(dumps, key=parse_date_from_dump, reverse=True)[0]

# Get XML files from latest dump
response = requests.get(f"{BASE_URL}{latest}/", timeout=30)
response.raise_for_status()
soup = BeautifulSoup(response.text, 'html.parser')
files = [link.get('href') for link in soup.find_all('a')
if link.get('href', '').endswith('.xml')]

if files:
newest_xml = sorted(files, reverse=True)[0]
print(f"{latest}/{newest_xml}")
sys.exit(0)
except Exception as e:
print(f"ERROR: {e}", file=sys.stderr)
sys.exit(1)

print("ERROR: No dumps found", file=sys.stderr)
sys.exit(1)

get_latest_dump()
PYTHON_EOF
}

# Function to download new XML
download_xml() {
local dump_info="$1"
local dump_dir=$(echo "$dump_info" | cut -d'/' -f1)
local xml_file=$(echo "$dump_info" | cut -d'/' -f2)
local url="https://xml.completenoobs.com/xmlDumps/${dump_info}"

echo "Downloading: $xml_file"
echo "From: $dump_dir"
echo "URL: $url"

if wget -O /tmp/new_dump.xml "$url" --progress=bar:force 2>&1; then
echo "Download successful!"
return 0
else
echo "Download failed!"
return 1
fi
}

# Function to backup current database
backup_database() {
echo "Creating database backup..."
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
mysqldump --user=wikiuser --password=wikipass completenoobs_wiki > /tmp/wiki_backup_${TIMESTAMP}.sql
echo "Backup created: /tmp/wiki_backup_${TIMESTAMP}.sql"
}

# Function to analyze and import changes
analyze_and_import() {
echo "Analyzing differences between XML and local wiki..."

# Create analysis and import script for MediaWiki 1.44+
cat > /tmp/analyze_import.php << 'PHP_EOF'
<?php
require_once '/var/www/html/maintenance/Maintenance.php';

class AnalyzeAndImport extends Maintenance {
private $db;
private $new_pages = [];
private $changed_pages = [];
private $unchanged_pages = [];

public function __construct() {
parent::__construct();
$this->addDescription('Analyze and selectively import from XML dump');
}

public function execute() {
$this->db = new mysqli('127.0.0.1', 'wikiuser', 'wikipass', 'completenoobs_wiki');

// MediaWiki 1.35+ uses slots and content tables
// Get existing pages with their content
$query = "
SELECT p.page_title, p.page_id, c.content_address, c.content_sha1
FROM page p
JOIN revision r ON p.page_latest = r.rev_id
JOIN slots s ON r.rev_id = s.slot_revision_id
JOIN slot_roles sr ON s.slot_role_id = sr.role_id
JOIN content c ON s.slot_content_id = c.content_id
WHERE p.page_namespace = 0 AND sr.role_name = 'main'
";

$result = $this->db->query($query);
if (!$result) {
$this->error("Database query failed: " . $this->db->error);
return;
}

$existing = [];
while ($row = $result->fetch_assoc()) {
// Get actual text content
$text_content = $this->getTextContent($row['content_address']);
$existing[$row['page_title']] = [
'id' => $row['page_id'],
'content' => $text_content,
'sha1' => $row['content_sha1']
];
}

// Parse XML and compare
$xml = simplexml_load_file('/tmp/new_dump.xml');

foreach ($xml->page as $page) {
$title = str_replace(' ', '_', (string)$page->title);
$xml_content = (string)$page->revision->text;

if (!isset($existing[$title])) {
// New page
$this->new_pages[$title] = $xml_content;
} else {
// Compare content using SHA1 for efficiency
$xml_sha1 = sha1($xml_content);

if ($existing[$title]['sha1'] !== $xml_sha1) {
// Content is different
$this->changed_pages[$title] = [
'local' => $existing[$title]['content'],
'xml' => $xml_content,
'page_id' => $existing[$title]['id']
];
} else {
$this->unchanged_pages[] = $title;
}
}
}

// Display summary
$this->output("\n=== Update Analysis ===\n");
$this->output("New pages to import: " . count($this->new_pages) . "\n");
$this->output("Changed pages found: " . count($this->changed_pages) . "\n");
$this->output("Unchanged pages: " . count($this->unchanged_pages) . "\n");

// Save analysis for review
file_put_contents('/tmp/update_analysis.json', json_encode([
'new' => array_keys($this->new_pages),
'changed' => array_keys($this->changed_pages),
'unchanged' => $this->unchanged_pages
], JSON_PRETTY_PRINT));

// Show changed pages with preview (limit to first 20 for readability)
if (count($this->changed_pages) > 0) {
$this->output("\n=== Changed Pages ===\n");
$count = 0;
$total_changed = count($this->changed_pages);

foreach ($this->changed_pages as $title => $data) {
$count++;
if ($count <= 20) {
$this->output("\n$count. $title\n");

// Create a simple diff preview (first 300 chars)
$xml_preview = substr($data['xml'], 0, 100);

// Save full diff to file
$safe_title = preg_replace('/[^a-zA-Z0-9_-]/', '_', $title);
$diff_file = "/tmp/diff_${safe_title}.txt";
file_put_contents($diff_file, "=== FULL DIFF FOR: $title ===\n\n");
file_put_contents($diff_file, "--- LOCAL VERSION ---\n", FILE_APPEND);
file_put_contents($diff_file, $data['local'] . "\n\n", FILE_APPEND);
file_put_contents($diff_file, "--- XML VERSION ---\n", FILE_APPEND);
file_put_contents($diff_file, $data['xml'], FILE_APPEND);

$this->output(" Preview: " . $xml_preview . "...\n");
}
}

if ($total_changed > 20) {
$this->output("\n... and " . ($total_changed - 20) . " more changed pages.\n");
$this->output("All diff files saved to /tmp/diff_*.txt\n");
}
}

// Interactive selection
if (count($this->new_pages) > 0 || count($this->changed_pages) > 0) {
$this->output("\n=== Import Options ===\n");
$this->output("1. Import new pages only (preserve all local changes)\n");
$this->output("2. Import new pages + update ALL changed pages (overwrites local changes)\n");
$this->output("3. Selective import (choose which updates to apply)\n");
$this->output("4. Cancel (no changes)\n");

// Save state for import script WITHOUT the XML object
$import_data = [
'new_pages' => $this->new_pages,
'changed_pages' => $this->changed_pages,
'xml_file' => '/tmp/new_dump.xml' // Save path instead of object
];

file_put_contents('/tmp/import_data.ser', serialize($import_data));
} else {
$this->output("\nNo changes detected. Your wiki is up to date!\n");
}
}

private function getTextContent($address) {
// Handle different content storage formats in MW 1.35+
if (strpos($address, 'tt:') === 0) {
// Text table reference
$text_id = substr($address, 3);
$result = $this->db->query("SELECT old_text FROM text WHERE old_id = $text_id");
if ($row = $result->fetch_assoc()) {
return $row['old_text'];
}
} elseif (strpos($address, 'es:') === 0) {
// External storage - would need special handling
return "[External storage content]";
}
// Direct content
return $address;
}
}

$maintClass = AnalyzeAndImport::class;
require_once RUN_MAINTENANCE_IF_MAIN;
PHP_EOF

cd /var/www/html
php /tmp/analyze_import.php
}

# Function to perform selected import
perform_import() {
local choice=$1

cat > /tmp/do_import.php << 'PHP_EOF'
<?php
require_once '/var/www/html/maintenance/Maintenance.php';

class DoImport extends Maintenance {
public function __construct() {
parent::__construct();
$this->addOption('mode', 'Import mode', true, true);
}

public function execute() {
$mode = $this->getOption('mode');
$data = unserialize(file_get_contents('/tmp/import_data.ser'));

// Load XML file
$xml = simplexml_load_file($data['xml_file']);

$new_imported = 0;
$updated = 0;

// Import new pages (always for modes 1-3)
if ($mode != '4') {
foreach ($data['new_pages'] as $title => $content) {
$this->importPage($title, $content, $xml);
$new_imported++;
$this->output("Imported new page: $title\n");
}
}

// Handle changed pages based on mode
if ($mode == '2') {
// Update all changed pages
foreach ($data['changed_pages'] as $title => $info) {
$this->output("Updating: $title\n");
if ($this->reimportPage($title, $xml)) {
$updated++;
$this->output("Updated page: $title\n");
} else {
$this->output("Failed to update: $title\n");
}
}
} elseif ($mode == '3') {
// Selective update
$this->output("\n=== Selective Import Mode ===\n");
$this->output("For each changed page, choose:\n");
$this->output(" y = yes, update this page\n");
$this->output(" n = no, keep local version\n");
$this->output(" d = show diff file\n");
$this->output(" a = update all remaining pages\n");
$this->output(" s = skip all remaining pages\n\n");

$update_all = false;
$skip_all = false;

foreach ($data['changed_pages'] as $title => $info) {
if ($skip_all) {
$this->output("Skipped: $title\n");
continue;
}

if ($update_all) {
if ($this->reimportPage($title, $xml)) {
$updated++;
$this->output("Updated: $title\n");
}
continue;
}

$this->output("\nPage: $title\n");
$this->output("Action (y/n/d/a/s): ");
$handle = fopen("php://stdin", "r");
$line = trim(fgets($handle));

while ($line == 'd') {
// Show diff
$safe_title = preg_replace('/[^a-zA-Z0-9_-]/', '_', $title);
$diff_file = "/tmp/diff_${safe_title}.txt";
if (file_exists($diff_file)) {
system("head -50 $diff_file");
$this->output("\n[Showing first 50 lines - full file at $diff_file]\n");
}
$this->output("Action (y/n/a/s): ");
$line = trim(fgets($handle));
}

if ($line == 'a') {
$update_all = true;
if ($this->reimportPage($title, $xml)) {
$updated++;
$this->output("Updated: $title\n");
}
} elseif ($line == 's') {
$skip_all = true;
$this->output("Skipped: $title\n");
} elseif ($line == 'y') {
if ($this->reimportPage($title, $xml)) {
$updated++;
$this->output("Updated: $title\n");
} else {
$this->output("Failed to update: $title\n");
}
} else {
$this->output("Skipped: $title\n");
}
}
}

$this->output("\n=== Import Complete ===\n");
$this->output("New pages imported: $new_imported\n");
$this->output("Pages updated: $updated\n");
}

private function importPage($title, $content, $xml) {
// Create single page XML for import
$tempFile = '/tmp/single_page_' . md5($title) . '.xml';
$singlePage = new SimpleXMLElement('<?xml version="1.0" encoding="utf-8"?><mediawiki></mediawiki>');

if ($xml->siteinfo) {
$siteinfo = $singlePage->addChild('siteinfo');
foreach ($xml->siteinfo->children() as $child) {
$siteinfo->addChild($child->getName(), (string)$child);
}
}

// Find and add the page
foreach ($xml->page as $page) {
if (str_replace(' ', '_', (string)$page->title) == $title) {
$newPage = $singlePage->addChild('page');
foreach ($page->children() as $child) {
if ($child->getName() == 'revision') {
$revision = $newPage->addChild('revision');
foreach ($child->children() as $revChild) {
$revision->addChild($revChild->getName(), (string)$revChild);
}
} else {
$newPage->addChild($child->getName(), (string)$child);
}
}
break;
}
}

$singlePage->asXML($tempFile);
exec("php /var/www/html/maintenance/importDump.php < $tempFile 2>&1");
unlink($tempFile);
}

private function reimportPage($title, $xml) {
// For updating existing pages, delete then reimport
$db = new mysqli('127.0.0.1', 'wikiuser', 'wikipass', 'completenoobs_wiki');

// Delete the existing page
$safe_title = $db->real_escape_string(str_replace(' ', '_', $title));
$db->query("DELETE FROM page WHERE page_title = '$safe_title' AND page_namespace = 0");

$db->close();

// Now import the new version
foreach ($xml->page as $page) {
if (str_replace(' ', '_', (string)$page->title) == $title) {
$tempFile = '/tmp/update_page_' . md5($title) . '.xml';
$singlePage = new SimpleXMLElement('<?xml version="1.0" encoding="utf-8"?><mediawiki></mediawiki>');

if ($xml->siteinfo) {
$siteinfo = $singlePage->addChild('siteinfo');
foreach ($xml->siteinfo->children() as $child) {
$siteinfo->addChild($child->getName(), (string)$child);
}
}

$newPage = $singlePage->addChild('page');
foreach ($page->children() as $child) {
if ($child->getName() == 'revision') {
$revision = $newPage->addChild('revision');
foreach ($child->children() as $revChild) {
$revision->addChild($revChild->getName(), (string)$revChild);
}
} else {
$newPage->addChild($child->getName(), (string)$child);
}
}

$singlePage->asXML($tempFile);
$result = exec("php /var/www/html/maintenance/importDump.php < $tempFile 2>&1", $output, $return);
unlink($tempFile);

return ($return === 0);
}
}

return false;
}
}

$maintClass = DoImport::class;
require_once RUN_MAINTENANCE_IF_MAIN;
PHP_EOF

cd /var/www/html
php /tmp/do_import.php --mode="$choice"
}

# Main execution
main() {
check_environment

# Start MariaDB if not running
service mariadb status > /dev/null 2>&1 || service mariadb start

# Wait for MariaDB
for i in {1..30}; do
if mysql -e "SELECT 1;" &>/dev/null; then
break
fi
sleep 1
done

CURRENT=$(get_current_version)
echo "Current version: $CURRENT"
echo ""

echo "Checking for updates..."
LATEST=$(check_for_updates 2>/dev/null)
if [ $? -ne 0 ] || [ -z "$LATEST" ] || [[ "$LATEST" == *"ERROR"* ]]; then
echo "Failed to check for updates"
exit 1
fi

echo "Latest available: $LATEST"
echo ""

# Always proceed to analysis even if versions match
# (there might be content updates in the same version)
echo "Proceeding with content analysis..."
echo ""

# Backup database
backup_database

# Download new XML
if ! download_xml "$LATEST"; then
echo "Failed to download new XML"
exit 1
fi

# Analyze differences
analyze_and_import

# Check if there are changes to import
if [ -f "/tmp/import_data.ser" ]; then
echo ""
read -p "Choose option (1-4): " -n 1 -r
echo

if [[ $REPLY =~ ^[1-4]$ ]]; then
if [ "$REPLY" != "4" ]; then
perform_import "$REPLY"

# Update version info
echo "Import: $LATEST" > /var/www/html/.last_import
echo "Date: $(date)" >> /var/www/html/.last_import

# Rebuild indices
echo "Rebuilding indices..."
php maintenance/rebuildrecentchanges.php
php maintenance/initSiteStats.php
else
echo "Update cancelled"
fi
else
echo "Invalid option. Update cancelled"
fi
fi

# Clean up temp files
rm -f /tmp/import_data.ser /tmp/update_analysis.json /tmp/diff_*.txt /tmp/analyze_import.php /tmp/do_import.php 2>/dev/null

echo ""
echo "Done!"
}

# Run main function
main "$@"
</syntaxhighlight>

=== 2.5: Entrypoint Script ===
<syntaxhighlight lang="bash">
nano entrypoint.sh
</syntaxhighlight>

<syntaxhighlight lang="bash">
#!/bin/bash

echo "Starting CompleteNoobs Wiki..."

service mariadb start

# Wait for MariaDB
for i in {1..30}; do
if mysql -e "SELECT 1;" &>/dev/null; then
echo "MariaDB ready!"
break
fi
sleep 1
done

echo ""
echo "CompleteNoobs Wiki ready at: http://localhost:8080"
echo "Admin login: admin / AdminPass123!"
echo ""
echo "Features:"
echo "- Complete wiki content imported from XML"
echo "- License notices on all pages (via PageNotice)"
echo "- SyntaxHighlight for code blocks"
echo "- YouTube video embedding"
echo "- Contribution Scores special page"
echo "- XML update system (preserves local edits)"
echo ""
echo "To check for updates: docker exec -it completenoobs_wiki /var/www/html/check_updates.sh"
echo ""

apache2-foreground
</syntaxhighlight>

== Step 3: Build and Run ==

=== 3.1: Build the Image ===
<syntaxhighlight lang="bash">
docker build -t completenoobs/wiki:latest .
</syntaxhighlight>
This will take several minutes.

=== 3.2: Run the Container ===
<syntaxhighlight lang="bash">
docker run -d -p 8080:80 \
-v completenoobs_mysql:/var/lib/mysql \
-v completenoobs_images:/var/www/html/images \
--name completenoobs_wiki completenoobs/wiki:latest
</syntaxhighlight>

== Step 4: Test Everything ==

=== 4.1: Check the Wiki ===
* Visit: http://localhost:8080
* You should see the PageNotice at the top
* Login with: admin / AdminPass123!

<div class="toccolours mw-collapsible mw-collapsed">
Change Admin Password:
<div class="mw-collapsible-content">

By default, the admin user's password is <code>AdminPass123!</code>. It's highly recommended to change this immediately. You can do this either through the wiki's web interface or directly in the Docker terminal.<br><br>

<b>Method 1: Change Password via Web Interface</b><br>
This is the easiest method. You can change your password directly from the wiki itself.<br>

1. Log in to your wiki with the default credentials: <code>admin</code> / <code>AdminPass123!</code>.<br>
2. Once logged in, click your username (<code>admin</code>) in the top-right corner of the page.<br>
3. From the drop-down menu, select <b>Preferences</b>.<br>
4. On the Preferences page, go to the <b>Password</b> tab.<br>
5. Enter the current password (<code>AdminPass123!</code>), then enter your new password twice.<br>
6. Click <b>Change password</b>.<br>

Your password is now changed, and you will need to use the new one for future logins.<br><br>

<b>Method 2: Change Password via Terminal (No-Email Reset)</b><br>
If you have forgotten the password or prefer to use the command line, you can reset it directly inside the Docker container using a MediaWiki maintenance script.<br>

1. <b>Access the container's shell</b> with the following command from your host machine:<br>
<syntaxhighlight lang="bash">
docker exec -it completenoobs_wiki bash
</syntaxhighlight>

2. Once inside the container, use the <code>changePassword.php</code> maintenance script to change the password. This is the modern, recommended way to run MediaWiki maintenance scripts.<br>
* Change <b>NEWPASSWORD</b> to your new password<br>
<syntaxhighlight lang="bash">
php /var/www/html/maintenance/run.php changePassword.php --user=admin --password=NEWPASSWORD
</syntaxhighlight>

3. Type <code>exit</code> to leave the container's shell.<br>

The admin password has now been reset. You can log in to your wiki with the new password.
</div>
</div>

=== 4.2: Test Extensions ===
* '''YouTube''': Edit any page, add <code><youtube>N9qYF9DZPdw</youtube></code>
* '''PageNotice''': Should already be visible at the top
* '''SyntaxHighlight''': Add code blocks with <nowiki><code><syntaxhighlight lang="python">code here</syntaxhighlight></code></nowiki>

=== 4.3: Check Status ===
<syntaxhighlight lang="bash">
docker exec completenoobs_wiki /var/www/html/check_status.sh
</syntaxhighlight>

== Step 5: XML Update Operations ==
*NOTE: update_xml.sh still needs alot of work, this just idea placeholder for now.
=== 5.1: Check for Updates (Interactive) ===
<syntaxhighlight lang="bash">
docker exec -it completenoobs_wiki /var/www/html/check_updates.sh
</syntaxhighlight>
This will:
* Check the CompleteNoobs XML repository for new dumps
* Compare with your current version
* Ask for confirmation before updating
* Import ONLY new pages (preserves your edits)
* Create a backup before making changes

=== 5.2: Force Update (Non-Interactive) ===
<syntaxhighlight lang="bash">
docker exec completenoobs_wiki bash -c "echo 'y' | /var/www/html/update_xml.sh"
</syntaxhighlight>

=== 5.3: Manual Update Process ===
<syntaxhighlight lang="bash">
# 1. Enter container
docker exec -it completenoobs_wiki bash

# 2. Check current version
cat /var/www/html/.last_import

# 3. Run update
/var/www/html/check_updates.sh

# 4. Exit container
exit
</syntaxhighlight>

== Step 6: Troubleshooting Commands ==
=== Access container shell: ===
<syntaxhighlight lang="bash">
docker exec -it completenoobs_wiki bash
</syntaxhighlight>

=== Edit configuration: ===
<syntaxhighlight lang="bash">
docker exec -it completenoobs_wiki nano /var/www/html/LocalSettings.php
</syntaxhighlight>

=== Check logs: ===
<syntaxhighlight lang="bash">
docker logs completenoobs_wiki
</syntaxhighlight>

=== View update logs: ===
<syntaxhighlight lang="bash">
docker exec completenoobs_wiki tail -f /tmp/mediawiki-debug.log
</syntaxhighlight>

=== Complete restart: ===
<syntaxhighlight lang="bash">
docker stop completenoobs_wiki
docker rm completenoobs_wiki
docker run -d -p 8080:80 \
-v completenoobs_mysql:/var/lib/mysql \
-v completenoobs_images:/var/www/html/images \
--name completenoobs_wiki completenoobs/wiki:latest
</syntaxhighlight>

== Expected Results ==
* Working wiki with imported CompleteNoobs content
* PageNotice visible at top of all pages
* All extensions functional
* Text editors (nano/vim) available in container
* Utility scripts for maintenance
* XML update system that preserves local edits

==need to add==
* way for user to backup there local custom wiki - xml exporter