If you’ve been building on Midnight or want to participate in the network without trusting third-party infrastructure, run your own full node. This tutorial takes you from a bare Ubuntu/Debian machine to a healthy, synced node, including common failure points such as dropped peers and getting stuck on block 1.

Target audience: Developers and node operators who are comfortable with the Linux command line and Docker.

Prerequisites:

• A Ubuntu 22.04 or Debian 12 server (bare metal or VPS)
• Docker Engine installed (covered below)
• Git installed
• A running Cardano-db-sync + PostgreSQL instance (covered in step 1)
• Open firewall on port 30333 (P2P)

What you’ll have by the end: A full node synced to Midnight’s Testnet, with monitoring commands and troubleshooting steps for common issues.

Understanding the node types

Before you spin anything up, it helps to know what you’re actually running. Midnight has four node types:

• Full node: syncs the chain, validates transactions, and serves real-time state queries. It prunes historical state older than 256 blocks by default. This is what most developers and node operators need.
• Archive node: the same as a full node but retains the entire chain history. Required for block explorers or deep historical queries. Uses more disk space.
• RPC node: exposes an HTTP/WebSocket API for DApps to interact with the chain programmatically.
• Boot node: helps new nodes discover peers. You don’t need to run one unless you’re contributing to network bootstrapping.

This tutorial focuses on the full node. Where the archive node diverges, this guide calls out the one flag you need to change.

Step 1: Set up Cardano-db-sync and PostgreSQL

Midnight operates as a Cardano Partnerchain. That means your Midnight node needs a live connection to a Cardano-db-sync instance to track relevant scripts on the Cardano blockchain. This is required. Your node will not function without it.

Clone the midnight-node-docker repository

The midnight-node-docker repository contains the official Docker Compose files for the entire stack.

git clone https://github.com/midnightntwrk/midnight-node-docker
cd midnight-node-docker

Install Docker Engine

If Docker isn’t already installed:

# Add Docker's official GPG key
sudo apt-get update
sudo apt-get install ca-certificates curl
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

# Add the repository
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-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io 
  docker-buildx-plugin docker-compose-plugin

Verify the installation:

docker --version
sudo systemctl status docker

You should see Active: active (running) in the status output.

Configure the Cardano-db-sync service

Open compose-partner-chains.yml in an editor:

nano compose-partner-chains.yml

Make the following changes:

1. Replace all default usernames and passwords with values only you know. Do not leave postgres / password123 in a production or publicly reachable environment.
2. Comment out the Ogmios service unless you are a block producer who needs it. Find the ogmios: block and add # to the start of each line.
3. Save the file.

Start Cardano-db-sync

docker compose -f compose-partner-chains.yml up -d

This starts Cardano-db-sync and PostgreSQL as background services.

Verify Cardano-db-sync is syncing

Install the PostgreSQL client if you don’t have it:

sudo apt-get install postgresql-client

Connect and run the sync progress query:

psql -h localhost -U your_postgres_user -d cexplorer -p 5432

Inside the PostgreSQL shell:

SELECT 100 * (
    EXTRACT(EPOCH FROM (MAX(time) AT TIME ZONE 'UTC')) -
    EXTRACT(EPOCH FROM (MIN(time) AT TIME ZONE 'UTC'))
) / (
    EXTRACT(EPOCH FROM (NOW() AT TIME ZONE 'UTC')) -
    EXTRACT(EPOCH FROM (MIN(time) AT TIME ZONE 'UTC'))
) AS sync_percent
FROM block;

You’ll see a number between 0 and 100. Cardano-db-sync must reach 100% before your Midnight node can operate correctly. On the Preview Testnet this typically takes several hours depending on your hardware and disk IOPS. Grab a coffee.

Tip: You can keep checking sync progress without entering the shell every time:

docker exec -it db-sync-postgres psql -U your_postgres_user 
  -d cexplorer -c 
  "SELECT 100 * (EXTRACT(EPOCH FROM (MAX(time) AT TIME ZONE 'UTC')) - 
  EXTRACT(EPOCH FROM (MIN(time) AT TIME ZONE 'UTC'))) / 
  (EXTRACT(EPOCH FROM (NOW() AT TIME ZONE 'UTC')) - 
  EXTRACT(EPOCH FROM (MIN(time) AT TIME ZONE 'UTC'))) 
  AS sync_percent FROM block;"

Step 2: Resource requirements

Before you start the Midnight node itself, make sure your machine meets the minimum specs. Running an undersized node is the fastest way to end up stuck on block 1 with peers constantly dropping.

Storage note: Low-IOPS disks, including spinning HDDs and cheap cloud volumes, often cause sync stalls and peer disconnections. If your node keeps falling behind the chain tip, check your disk I/O before anything else:

iostat -x 1 5

Look at the %util column. If it stays above 80%, your disk is the bottleneck.

Step 3: Configure and start the full node

Check the current node version

Always use the version listed in the compatibility matrix. At the time of writing, the current node version is 0.22.3 on Preview and Preprod.

Create the Docker Compose file

Create a file called compose-midnight-node.yml in your working directory:

nano compose-midnight-node.yml

Paste the following:

version: "3.8"

services:
  midnight-full-node:
    image: midnightnetwork/midnight-node:0.22.3
    container_name: midnight-full-node
    platform: linux/amd64
    restart: unless-stopped
    ports:
      - "30333:30333"
    volumes:
      - midnight-data:/node
    environment:
      MIDNIGHT_NODE_IMAGE: "midnightnetwork/midnight-node:0.22.3"
      POSTGRES_HOST: "your_postgres_host"
      POSTGRES_PORT: "5432"
      POSTGRES_USER: "your_postgres_user"
      POSTGRES_PASSWORD: "your_postgres_password"
      POSTGRES_DB: "cexplorer"
      DB_SYNC_POSTGRES_CONNECTION_STRING: "psql://your_postgres_user:your_postgres_password@your_postgres_host:5432/cexplorer"
      BASE_PATH: "./node/chain/"
      CFG_PRESET: "testnet-02"
    command: >
      --chain=/res/testnet-02/testnetRaw.json
      --no-private-ip

volumes:
  midnight-data:

Replace all placeholder values (your_postgres_host, your_postgres_user, your_postgres_password) with the credentials you set in step 1.

If you want an archive node instead, add --pruning archive to the command block:

    command: >
      --chain=/res/testnet-02/testnetRaw.json
      --pruning archive
      --no-private-ip

Start the node

docker compose -f compose-midnight-node.yml up -d

The node starts in the background. Give it 30–60 seconds to initialize, then check that it’s running:

docker ps

You should see midnight-full-node with status Up.

Step 4: Monitor the initial sync

Stream logs in real time

docker logs -f midnight-full-node

During a healthy sync, you’ll see lines like:

2024-05-04 12:00:01 ⚙️  Syncing 45.2 bps, target=#187432 (12 peers), best: #8492 (0x1a2b…c3d4), finalized #8448 (0x5e6f…7a8b)

Key things to watch:

• bps: blocks per second being synced. A healthy node syncs at several dozen bps during initial sync.
• target=#XXXXXX: the current chain tip.
• best: #XXXXXX: your local best block. This should climb steadily.
• finalized #XXXXXX: the last finalized block. This should trail your best block by a small number.
• (N peers): the number of connected peers. You want to see 5 or more.

Monitor block height

To check your current block height at any point without reading the full log stream:

docker logs midnight-full-node 2>&1 | grep "best:" | tail -1

Or query the node’s RPC endpoint directly (if you’ve also started an RPC node):

curl -s -H "Content-Type: application/json" 
  -X POST 
  -d '{"jsonrpc":"2.0","id":1,"method":"chain_getHeader","params":[]}' 
  http://127.0.0.1:9944 | python3 -m json.tool

The number field in the response is the current best block in hex. Convert it:

printf "%dn" 0x2DB20   # example output: 187168

Check peer count

docker logs midnight-full-node 2>&1 | grep "peers" | tail -5

A healthy node shows 5–50 peers. If you’re consistently seeing 0–2 peers, see the troubleshooting section below.

Step 5: Verify your node is synced and healthy

Once you believe your node has caught up, confirm it’s genuinely at the chain tip rather than just stopped at a stale block.

Check the sync gap

docker logs midnight-full-node 2>&1 | grep "Syncing|Idle" | tail -5

When fully synced, the log line changes from Syncing to Idle:

2024-05-04 14:22:01 💤 Idle (14 peers), best: #187432 (0x1a2b…c3d4), finalized #187428 (0x5e6f…7a8b)

Idle means your node is at the tip and waiting for new blocks. The best block number should match (or be within a few blocks of) the Midnight block explorer.

Compare with the network tip

You can check the current network block height against the Midnight block explorer. If your node’s best block is within 5–10 blocks of the explorer, you’re synced.

Verify P2P port is reachable

From another machine or using a port checking tool:

nc -zv your_server_ip 30333

If the port is closed, your node can’t accept inbound peer connections, which limits your peer count and sync speed. Open it in your firewall:

sudo ufw allow 30333/tcp
sudo ufw reload

Step 6: Troubleshooting common issues

Node is stuck on block 1 (or a very low block number)

This is the most common issue reported in the community. There are three usual causes:

1. Cardano-db-sync hasn’t finished syncing

Your Midnight node requires a fully synced Cardano-db-sync instance. If sync_percent in PostgreSQL is below 100, your node stalls. Check it with the query from step 1, and wait until it reaches 100%.

2. The PostgreSQL connection string is wrong

Double-check your DB_SYNC_POSTGRES_CONNECTION_STRING environment variable. A common mistake is using localhost as the host when PostgreSQL is running in a different Docker container. Use the actual container name or host IP instead.

Test the connection directly:

psql "psql://your_postgres_user:your_postgres_password@your_postgres_host:5432/cexplorer" 
  -c "SELECT count(*) FROM block;"

If this fails, fix your connection string before restarting the node.

3. Node image version mismatch

Running an outdated node image against the current Testnet causes immediate sync failure. Always verify against the compatibility matrix and pull the latest image:

docker pull midnightnetwork/midnight-node:0.22.3
docker compose -f compose-midnight-node.yml up -d --force-recreate

Peers keep disconnecting

If peer counts keep climbing to 5 and then dropping back to 0, check these items:

1. Port 30333 is not publicly reachable

This is the most common cause. Even if Docker is forwarding the port locally, your firewall or cloud security group might be blocking inbound connections. Peers connect to you on port 30333; if they can’t reach it, they time out and disconnect.

Check your firewall:

sudo ufw status

If 30333 isn’t listed as ALLOW, add it:

sudo ufw allow 30333/tcp
sudo ufw reload

If you’re on a cloud VM (AWS, GCP, DigitalOcean), also check your provider’s inbound security group or firewall rules in the web console.

2. The --no-private-ip flag is missing

Without --no-private-ip, your node advertises its private/internal IP address to peers. External peers try to connect to an address they can never reach, fail, and disconnect. Make sure this flag is in your command block.

3. NAT or double-NAT

If your server is behind NAT (common with home servers or some VPS setups), peers can’t initiate connections to you. You either need to set up port forwarding at the router level, or use a VPS with a public IP.

4. Disk I/O bottleneck

High disk utilisation causes the node to fall behind processing blocks, which causes peers to consider it unresponsive and drop the connection. Check with:

iostat -x 1 10

Upgrade to an SSD with 30,000+ IOPS if %util is consistently high.

Node crashes or restarts frequently

Check the logs for the last error before restart:

docker logs midnight-full-node 2>&1 | grep -E "ERROR|WARN|panic" | tail -20

Common causes:

• Out of memory: check with free -h. If your machine has less than 16 GB RAM, the node may OOM. Add swap as a temporary workaround:

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

• Docker volume corruption: rare, but possible after a hard shutdown. Recreate the volume:

  docker compose -f compose-midnight-node.yml down
  docker volume rm midnight-data
  docker compose -f compose-midnight-node.yml up -d

Note: this wipes your sync progress and starts from block 0.

Checking connectivity manually

To confirm your node can actually talk to the network:

# Check if P2P port is listening
ss -tlnp | grep 30333

# Test reachability from outside (run on a different machine)
nc -zv your_server_ip 30333

# Check how many peer connections are currently open
docker exec midnight-full-node ss -tn | grep 30333 | wc -l

Keeping your node up to date

Midnight is in active Testnet development. Node versions update frequently, and running an outdated version will cause your node to stop syncing or get rejected by peers.

Subscribe to the Midnight Discord channel on Discord and watch the release notes for new node versions.

When a new version drops, update like this:

# Pull the new image
docker pull midnightnetwork/midnight-node:NEW_VERSION

# Update the version in your compose file
nano compose-midnight-node.yml
# Change 0.22.3 to NEW_VERSION in both the image: and MIDNIGHT_NODE_IMAGE: lines

# Restart with the new image
docker compose -f compose-midnight-node.yml up -d --force-recreate

What to do next

You now have a full node running, synced, and healthy. From here:

• Set up an RPC node: if you want your DApp to talk directly to your own infrastructure instead of a public endpoint, follow the RPC node setup guide.
• Explore the DApp quickstart: start building a privacy-preserving DApp on top of the network you’re now running: Getting started.
• Join the community: the Midnight developer forum and Discord are the best places to ask questions, report issues, and follow network updates.
• Share your work: if you write about your node setup or share what you built on top of it, tag @midnightntwrk on X and use #MidnightforDevs.

This tutorial reflects Midnight node v0.22.3 on the Preview/Preprod Testnet. Always check the compatibility matrix before updating your setup.

Why We Built a Faster Wiki

I first tried to build a wiki in 2010. Working prototype, decent idea, abandoned prematurely. Sixteen years later, the market has barely moved. The tools got heavier, the page loads got slower, and everyone just… accepted it.

I didn’t accept it. So I built Raccoon Page.

The problem nobody fixed

Here’s what happens in most companies: someone writes documentation. It goes into the wiki. A week later, a new hire needs that documentation. They open the wiki. They wait. The page loads in three, four, five seconds. They try search. The results are irrelevant. They close the tab and walk over to a coworker’s desk.

The wiki is now a graveyard. The knowledge is there, technically, but nobody uses it because the tool is slower than asking Dave.

This isn’t a people problem. It’s a tools problem. And it affects more than just software teams — every industry that relies on documentation feels this. Financial analysts looking up compliance docs during live calls. Operations managers referencing SOPs in a warehouse on a mediocre tablet. Support agents pulling up knowledge articles while a customer waits in silence.

The wiki market has been stagnant for fifteen years. The dominant tools are either slow and enterprise-bloated, or flexible-but-sluggish all-in-one workspaces that treat the wiki as an afterthought. Nobody shipped a wiki that’s both fast and pleasant to use.

What Raccoon Page is

Raccoon Page is a wiki. Not a workspace, not a database, not a project management tool that also has pages. A wiki. It does what your current wiki does — pages, hierarchy, search, comments, version history, permissions — except it doesn’t waste your time doing it.

Pages load near-instantly. There are no spinners on basic navigation. Search is fast and typo-tolerant. If you’re a keyboard person, there’s a command palette, shortcuts for everything, and slash commands in the editor. If you’re not a keyboard person, it’s still just a clean, fast wiki — no learning curve required.

The speed isn’t an accident. It’s the first architectural decision I made and the one that shaped everything after it. PostgreSQL with careful query design instead of an ORM that generates page-long joins. Server-side rendering of the critical path. No client-side data fetching waterfalls on page load. Every technical choice was filtered through: “Does this keep the page load fast?”

Why import matters more than features

I’ve watched enough SaaS launches to know the pattern: team evaluates new tool, likes it, starts a trial, realizes migrating their existing content would take weeks, abandons the trial. The switching cost kills adoption, not the product quality.

So I built import before I built templates, before threaded comments, before half the features on my roadmap. Raccoon Page imports from Confluence (XML export), Notion (Markdown/CSV export), and Obsidian (vault zip). The whole process takes about ten minutes for a typical team wiki. You also export to Obsidian-compatible Markdown, so you’re never locked in.

This was originally a month-two feature. I moved it to launch because I realized the import story changes the entire sales pitch. It’s not “try our wiki and rebuild your content.” It’s “bring your content and see it load faster.”

What we built, what we deferred

Real-time co-editing shipped at launch. Multiple people can work on the same page simultaneously — cursors, selections, and edits all sync live. This was originally deferred, but we pulled it forward because every competitor has it and it’s table-stakes for team adoption. No whiteboards yet — that’s still on the roadmap.

Authentication supports both email/password and OAuth (Google, GitHub), so your team can sign in the way they already work. Dark theme is the default, with a light mode toggle for those who prefer it.

There’s no AI search yet. I deliberately deferred it. AI-powered search sounds impressive in a feature matrix, but it costs real money per query — money that eats margin at $8/user/month. Raccoon Page ships with PostgreSQL full-text search that’s fast and actually works. AI synthesis will come later as a premium feature, once there’s revenue to fund it.

There are no Slack integrations, no API, no SAML SSO. All planned. None necessary for the first ten teams to get value.

Every feature we shipped or deferred was a deliberate trade. The filter was simple: does it reduce churn, drive conversion, or remove a barrier to adoption? If not, it can wait.

The honest competitive picture

Confluence is the market leader and it deserves respect. Deep Jira integration, enterprise compliance, decades of trust. If your organization runs on Jira and has a formal procurement process, Confluence is probably staying. I’m not here for that fight.

Notion is beautiful and flexible. If you need a workspace that does everything — databases, projects, docs, wikis — Notion is genuinely good at being everything. It’s less good at being a fast wiki specifically, and the performance at scale is a known pain point, but it earns its 100 million users.

Outline is the closest thing to what I’m building — open-source, fast, clean. If you want to self-host your wiki and have the infrastructure skills to do it, Outline is a solid choice. Raccoon Page is for teams who want the speed without the operational overhead — managed SaaS, one-click import, ready to go.

I’m not building the wiki for everyone. I’m building it for teams where the documentation is supposed to help but the tool gets in the way instead.

The boring technical details (for those who care)

The backend is C# on .NET, which surprises people who expect a wiki startup to be written in TypeScript or Go. I have eight years of Go experience and chose C# anyway — better AI code generation quality, a richer type system for the kind of dynamic content a wiki handles, and a more stable package ecosystem. The right tool for the job isn’t always the familiar one.

The editor is TipTap, built on ProseMirror. Headless, extensible, battle-tested. Headings, lists, code blocks with syntax highlighting, callouts, tables, images, slash commands. It’s not trying to be Google Docs — it’s trying to be a good wiki editor that stays out of the way.

The database is PostgreSQL. Not because it’s trendy, but because 80% of a wiki’s data model is relational (users, permissions, spaces, memberships) and the remaining 20% (page content) fits perfectly in JSONB columns. MongoDB would have meant reinventing relational integrity for the majority of the schema.

The whole thing runs on DigitalOcean for about $100/month. No Kubernetes cluster, no microservices, no distributed systems. One process, one database, one server. It’s enough for thousands of users and it’s simple enough for one person to operate at 3 AM when something breaks.

A small team, one bet

We’re two co-founders. No funding, no investors. The code is roughly 80-90% generated by AI (Claude Code, specifically), which is the only reason a tiny team can ship a full-featured wiki in a few months. I write the architecture and make the technical decisions. My co-founder handles testing, and increasingly the legal and marketing side. The AI writes the bulk of the implementation. It’s a force multiplier that didn’t exist when I first tried this in 2010.

This is a bootstrapped bet with a 12-18 month competitive window. AI-native wiki tools are coming — probably dozens of them. The question is whether a fast, focused, well-imported wiki can establish a foothold before the market gets crowded.

We think it can. Not because the technology is revolutionary, but because the problem is so obvious and so neglected that even a competent solution wins. Your wiki should not be slower than asking a coworker. That’s it. That’s the whole pitch.

Try it

Raccoon Page is live at raccoon.page. Free tier: 3 users, 1 space, 100 pages. Enough to decide if speed matters to you.

If you’re on Confluence, Notion, or Obsidian, bring your content. A typical team wiki imports in about ten minutes. See your own pages load fast, not a demo with cherry-picked content.

If it’s not for you, the export button is right there. No lock-in, no tricks.

Building a Browser-Based Inkarnate Alternative for D&D Battle Maps

When people search for an Inkarnate alternative, they are usually not asking for one single thing.

Some want a beautiful fantasy world map.

Some want a regional map for a novel.

Some want a city map.

But a lot of Dungeon Masters want something much more practical:

“I need a playable D&D battle map for this week’s session, and I do not want to spend the whole evening fighting a heavy tool.”

That is the problem I am building around with RPGMapEditor.com.

It is a browser-based RPG map editor focused on encounter-scale battle maps for D&D, TTRPGs, Roll20, Foundry VTT, and printable tabletop sessions.

Not a full fantasy illustration suite.

Not a worldbuilding atlas.

Not a replacement for every cartography tool.

A faster way to create readable, playable battle maps in the browser.

Quick answer: is RPGMapEditor.com an Inkarnate alternative?

Yes, but only for a specific workflow.

RPGMapEditor.com is an Inkarnate alternative if your main goal is to create grid-based battle maps for D&D or other tabletop RPG sessions.

It is not trying to replace Inkarnate for polished world maps, regional fantasy maps, or large illustrated map galleries.

The difference is simple:

If your weekly pain is encounter production, not fantasy illustration, a narrower tool can be better.

Why another RPG map editor?

Most DMs do not need a perfect map.

They need a map that is:

• readable
• fast to make
• aligned to a grid
• easy to revise
• exportable to a VTT
• good enough for actual play

That sounds obvious, but many map tools slowly become asset browsers, art suites, marketplace platforms, or full VTT automation systems.

Those can be powerful.

They can also be slow when the party unexpectedly goes into a cave, tavern, forest road, sewer, bridge, or ruined chapel you did not prepare.

The bet behind RPGMapEditor.com is that a focused editor can win by reducing decisions.

Open the browser.

Start from a blank canvas or demo map.

Paint terrain.

Place props.

Check the grid.

Export PNG.

Use it in Roll20, Foundry VTT, or at the table.

That workflow matters more than having every possible feature on day one.

What RPGMapEditor.com supports today

The current shipped workflow focuses on practical battle map creation:

• browser-based map editing
• terrain painting
• props and stamps
• grid-based battle maps
• demo projects
• PNG export
• free accounts with limited saved maps
• optional Studio plan for more saved maps and sharing features

That means the tool is already useful for a common tabletop workflow:

1. Create a tactical map.
2. Export it as a PNG.
3. Upload it into Roll20 or Foundry VTT.
4. Align the grid inside your VTT.
5. Run the encounter.

This is intentionally simple.

PNG export is not glamorous, but it is one of the most universal handoff formats for virtual tabletops.

What RPGMapEditor.com does not claim yet

This matters because fake comparison articles are useless.

RPGMapEditor.com does not currently claim to export:

• native Foundry VTT scenes
• Roll20 dynamic lighting
• automatic walls
• automatic doors
• full VTT automation data

For now, the product focuses on the visual battle map.

Your VTT still handles tokens, walls, lighting, fog, automation, initiative, sheets, and live gameplay.

That is not a weakness if the user understands the scope.

It becomes a weakness only if the marketing lies.

Why browser-based map editing matters

Desktop map tools can be powerful, but they create friction:

• installation
• updates
• local files
• asset folders
• OS compatibility
• device switching
• heavier onboarding

A browser-based RPG map editor removes some of that friction.

For many DMs, the best tool is not the one with the longest feature list.

The best tool is the one they actually open on a weeknight when the session is tomorrow.

That is where browser-based editing has a real advantage.

You can open a demo project, test the editor, and understand the workflow before committing to an account or paid plan.

The real comparison: art suite vs encounter tool

Inkarnate is known for fantasy map creation across multiple styles.

That is a strength.

But broad tools often serve broad use cases:

• world maps
• regional maps
• city maps
• fantasy art scenes
• map galleries
• cloneable maps
• large asset libraries

RPGMapEditor.com is narrower.

It is aimed at:

• D&D battle maps
• grid-based tactical scenes
• encounter prep
• Roll20 PNG workflows
• Foundry VTT background map workflows
• browser-first editing
• quick iteration

That narrower positioning is the product strategy.

Not “more features than Inkarnate.”

Not “better at everything.”

Just faster battle map prep for the use case where speed matters.

A simple example workflow

Imagine you need a forest ambush map for tomorrow’s session.

You do not need a masterpiece.

You need:

• a road
• trees
• cover
• difficult terrain
• readable grid spacing
• maybe a ruined cart
• maybe rocks or elevation hints
• a clean export

In RPGMapEditor.com, the intended workflow is:

1. Start from a blank map or demo.
2. Paint the main playable terrain.
3. Add props that affect tactics.
4. Keep the grid readable.
5. Export a PNG.
6. Import it into Roll20 or Foundry VTT.
7. Add tokens, walls, lighting, and gameplay details inside the VTT.

That is the practical DM workflow.

The map does not need to win an art contest.

It needs to make combat understandable.

Who should try RPGMapEditor.com?

RPGMapEditor.com is worth testing if you are:

• a Dungeon Master making regular battle maps
• a GM running grid-based TTRPG encounters
• preparing maps for Roll20
• preparing scene backgrounds for Foundry VTT
• tired of installing desktop tools for simple maps
• looking for a lightweight browser-based RPG map editor
• comparing Inkarnate alternatives specifically for battle maps

It is probably not the right first choice if you mainly want:

• a giant world map
• a polished regional fantasy map
• advanced illustration tools
• a huge established asset marketplace
• automatic VTT walls and doors today

That distinction is important.

A focused tool should be judged by the job it is designed to do.

Why I am building it this way

The product philosophy is simple:

A battle map editor should help DMs reach a playable map faster.

That means the important questions are not only technical.

They are product questions:

• Can a new user understand the editor quickly?
• Can they make a usable map in one sitting?
• Can they export without confusion?
• Can they reopen and revise maps later?
• Can the grid stay readable?
• Can the map survive real VTT usage?
• Does the workflow reduce prep stress?

Those questions matter more than adding another shiny feature.

RPGMapEditor.com vs Inkarnate: the honest version

Here is the honest comparison.

Use Inkarnate or a broader fantasy map tool when you want a polished fantasy illustration workflow, world maps, regional maps, city maps, or access to a mature asset ecosystem.

Use RPGMapEditor.com when you want a focused browser-based battle map editor for encounter prep, terrain painting, props, grid maps, saved projects, and PNG export for VTT use.

That is the lane.

And for many DMs, that lane is enough.

Try it

You can try the browser-based editor here:

RPGMapEditor.com

Useful pages:

• RPG Map Editor features
• Inkarnate alternative comparison
• D&D map maker
• Dungeon map maker
• Roll20 battle map export
• Foundry VTT battle map export

If you are a DM, the best test is simple:

**Create one encounter map.

Export it.

Use it in your actual VTT.

If it saves prep time, the product is doing its job.**

What is Apache Kafka

Main Concepts

Event

• A record that something actually happened, i.e., a message
  When you read/write to Kafka, you do this in the form of events

Producers
Use the producer api to produce and send events

Topics

• Events are organized and durably organized into topics
• Topics are categorized into which the events are published that trigger other actions

Consumers
Those who subscribe (read and process) the events sent by producers
Real time processing(Streams)
Partitions for Scalability and Performance
Consumer Groups for scalable Message Consumption

Kafka Brokers

• A server that stores data(messages), topics, and manages message distribution to consumers
• Fault tolerance since topic partitions are distributed across multiple brokers
• Each partition has a leader broker and multiple replicas
  Apache Kafka – stores messages on disk for a certain configurable retention period
  Benefits of data retention
• Real-time processing of data
• consumers can read multiple times they want
• replay of messages, debugging of historical data
  Apache Kafka focuses on event streaming and long-term data retention
  Optimized for high throughput

Zookeper
Cluster Management
maintains a registry of all brokers in the cluster

Leader Election
Each Kafka partition has a leader broker
Metadata Configuration
And traditionally, Kfaka used an external tool Zookeeper for managing metadata and coordination of tasks in a distributed system
External dependency for Kafka
The newer versions of Kafka from v3 now use KRaft
Kafka version 3.0 and above

• removed the dependency for zookeeper and introduced KRaft
• And metadata is now being managed natively within Kafka brokers
• Raft consensus Algorithm for leader election

I’ve been writing Go for a while now, and somewhere along the way something shifted.

My code started feeling less like “code that happens to be in Go” and more like… Go code. Hard to explain, but you notice it when it happens.

Go has patterns. Not rules exactly, but ways of doing things that show up everywhere across the language and the ecosystem. Error handling. Naming. Control flow. The way you structure types. You start picking them up gradually, and when you finally start using them yourself, your code starts to feel right in a way that’s difficult to articulate.

This article is just me sharing the ones that clicked for me. Some are well-known idioms. Some are just habits I picked up from reading enough Go code written by people who clearly knew what they were doing.

This isn’t the official take though. For that, go read Effective Go. It’s from the Go team and it’s genuinely good. Think of this as the stuff I wish I’d come across earlier.

Okay. Let’s get into it.

1. Go Makes You Deal With Uncertainty Explicitly

One of the first things that hits you when you start writing Go is that its error handling is very explicit.

Two patterns show up everywhere, and once you understand what they’re actually doing, a huge chunk of Go code starts making sense.

err != nil : the error check you’ll write a thousand times

In most languages, errors get thrown and caught somewhere up the chain. Go doesn’t do that. Functions that can fail return the error directly, and you check it right there.

user, err := getUserByID(id)
if err != nil {
    return err
}

At first this feels repetitive. You write if err != nil so many times you start doing it in your sleep. But that’s kind of the point. There’s no hidden control flow. No wondering where an exception might surface. The error is right there, and you deal with it or you pass it up. It’s your call.

What makes it even nicer is redeclaration. If you’re chaining multiple calls, you don’t need a new err variable each time. Go lets you reuse the one err variable with := as long as at least one variable on the left is new:

user, err := getUserByID(id)
if err != nil {
    return err
}

profile, err := getProfile(user.ID)
if err != nil {
    return err
}

Same err, reassigned each time. You just keep going down the chain, handling as you go.

The comma-ok idiom: “does this even exist?”

The other pattern is comma-ok. You see it when reading from a map, doing a type assertion, or receiving from a channel:

value, ok := someMap[key]
if !ok {
    // key doesn't exist
}

The second value, ok , is just a boolean. It’s Go’s way of saying: this operation might not give you anything useful, here’s how you check.

It’s really the same idea as err != nil. Go doesn’t like silent failures. It hands you the result and the signal that tells you whether it’s safe to use.

This has been pretty good for me, cause before Go I tended to skip error checks and just sort of assume things exist.

2. Naming Things the Go Way

Go is pretty opinionated about names. Not in a loud way, just in a “this is how we do it here” way. Two things tripped me up early on.

Package-scoped names

When I started out I was writing things like jobs.JobsService and companies.CompaniesService. Felt thorough. Felt descriptive. Also felt redundant the moment someone pointed it out to me.

The package name is already doing half the work. jobs.Service says exactly the same thing as jobs.JobsService, just without the stutter. Go leans on this everywhere. You’re not writing the type in isolation, you’re writing it in context. Let the package carry its weight.

Once I internalized this, I started catching myself doing it with other things too. jobs.JobFilter becoming jobs.Filter. users.UserStore becoming users.Store. Much cleaner, much simpler… don’t you think?

Interface names: Reader, Writer, and friends

This one confused me for longer than I’d like to admit.

Go’s convention is to name interfaces after what they do, usually as a single word with an -er suffix. Reader. Writer. Stringer. Handler. It sounds simple but it’s actually a really clean system once it clicks. If your type has a Read method, it’s a Reader. That’s it.

The practical payoff is standard library function signatures become much easier to read and understand. When you see a function that accepts an io.Writer, you immediately know: anything with a Write method works here. os.File, bytes.Buffer, http.ResponseWriter. They all qualify.

3. Writing Clean Control Flow

This section is about the stuff that makes Go code easy to read top to bottom. The patterns here are some of my favorite, even though they’re much more convenience type patterns than patterns that have a lot to do with whether your program runs correctly.

Early returns instead of if-else chains

I used to write a lot of this:

if condition {
    // do thing
} else if other condition {
    // do other thing
} else {
    // fallback
}

Go developers tend to flip that around. Handle the bad cases first, return early, and let the happy path sit at the bottom with no indentation:

if !condition {
    return err
}

if !otherCondition {
    return err
}

// happy path here

It’s a small shift, but one that I think makes a big difference. With this pattern, you don’t need to mentally track multiple branches. You just read down.

Chaining calls with redeclaration

This one I use constantly. We already mentioned it a little. When you’re making multiple calls that can fail, you don’t need a fresh err variable each time. Go lets you reuse it with := as long as at least one variable on the left side is new:

user, err := getUserByID(id)
if err != nil {
    return err
}

profile, err := getProfile(user.ID)
if err != nil {
    return err
}

posts, err := getPostsByUser(user.ID)
if err != nil {
    return err
}

Same err the whole way down. It keeps things clean and you’re never managing a bunch of err1, err2, err3

Only take what you need from a range loop

If you’re ranging over a slice and you only need the index, you don’t have to assign the value at all:

for i := range someSlice {
    // just the index
}

No need for the _ placeholder.

4. Working With Types Intentionally

Go’s type system is one of the things I’ve come to genuinely appreciate. It nudges you toward writing code that’s flexible but safe.

Interfaces for swappability

An interface in Go is just a contract. If your type has these methods, it satisfies the interface. That’s it.

The reason this matters practically is swappability. Say you have a service that depends on a repository. If that repository is a concrete type, you’re locked in. If you want to, for example, swap it out in tests, you can’t easily do that. Not without a refactor. But if you depend on an interface instead:

type UserRepository interface {
    GetByID(id int) (User, error)
    Create(u User) error
}

Now anything that implements those methods works. Your real database repository. A mock for tests. Whatever.

I use this pattern constantly in my projects now. It keeps things separate in a way that actually helps when things get complicated.

Small pure functions, orchestrated by bigger ones

Not exclusively a Go thing. More a general organizational pattern, but I’ve been doing it a lot in Go.

The idea is simple. Write small functions that do one thing and don’t touch anything outside themselves. Then write a bigger function whose only job is calling those smaller ones in the right order.

func processJob(job Job) error {
    if err := validateJob(job); err != nil {
        return err
    }

    normalized := normalizeJob(job)

    if err := saveJob(normalized); err != nil {
        return err
    }

    return nil
}

validateJob, normalizeJob, saveJob , each one does its thing. processJob just calls and organizes them. When something breaks, you know exactly where to look.

make for slices when you know the size

If you know upfront how many elements a slice will have, initialize it with make:

results := make([]Job, len(input))

for i, item := range input {
    results[i] = process(item)
}

Without make, you’d have to append each element, and you lose the ability to assign by index directly.

Embedding

Honestly, I don’t use this one that often. But when I do come across the need, it’s very useful.

Embedding lets one struct inherit the fields and methods of another by simply listing it in the inheriting struct:

type Animal struct {
    Name string
}

func (a Animal) Speak() string {
    return a.Name + " makes a sound"
}

type Dog struct {
    Animal
    Breed string
}

Dog gets Speak() for free

5. Concurrency: Getting a Response Back

Go’s concurrency model is one of its best features. Goroutines are cheap, channels are elegant, and the whole thing just makes sense once it clicks. Most of the time when you spin up a goroutine you’re firing something off and not waiting for a response. But sometimes you need one.

The pattern I’ve used for this is adding a result channel directly to the struct:

type Client struct {
    conn    net.Conn
    msgCh   chan string
    resultCh chan error
}

When the goroutine finishes its work, it sends the result down resultCh. The caller is sitting on the other end waiting for it:

go client.handleMessage(msg)

if err := <-client.resultCh; err != nil {
    log.Println("something went wrong:", err)
}

I ran into this pattern building a netcat group chat app. Multiple clients, concurrent connections, and I needed to know when something failed. Passing the result channel on the struct kept everything organized without having to thread channels through every function signature.

Wrapping Up

Here’s the thing about idiomatic Go. Nobody sits down and studies it all at once. You pick it up gradually. You read someone else’s code and think “oh, that’s a cleaner way to do that.” You get a review comment. You break something and figure out why. Slowly your code starts looking more like the language it’s written in.

The patterns in this article are just the ones that stuck for me. Error handling that forces you to be explicit. Naming that lets the package do the talking. Control flow that reads like a straight line. Types that stay flexible without getting complicated.

None of it is revolutionary. That’s kind of the point. Go is not a revolutionary language. It’s a deliberate one. And the more you write it, the more you realize that the “boring” choices are usually the right ones.

If you want the proper, structured breakdown of idiomatic Go, go read Effective Go. It’s from the people who built the language. This was just me passing on the stuff I wish I’d had earlier.

Now go write some Go. You’ll figure the rest out.