Mac/Linux beginner's guide for ORD development

1_README_bitcoin_mac.md

Ord Guide for Mac

Main source for this: Mac beginner's guide by ETS – This whole guide is a blatant copy & paste, I deserve zero credits!

This guide mostly assumes a primary SSD and an external SSD, formatted as APFS. If you want to follow the commands verbatim, name your external SSD volume as ord-dev. You'll still need ~100 GB free on your internal disk, as only the bitcoin blocks are moved to the external SSD. This configuration allows for moving the bulk of the storage needs to the external but leaving enough in the default locations to make commands easier.

⚠️ This guide won't work well if your primary or external storage are on a spinning disk. SSD only! Like really, you will regret your wasted time otherwise! Also make sure that you have a lot of memory – otherwise ord will never finish. Even machines with 32 GB+ are struggling sometimes these days. Go for 64 GB!

1️⃣ INSTALL HOMEBREW

Install Homebrew from http://brew.sh/
During installation you may be prompted for a password. This is your main Mac password and you won't see any letters as you type it. After typing it, press enter to continue.

⚠️ When installation completes, follow the steps listed in "Next steps" to add Homebrew to your path.

2️⃣ INSTALL BITCOIN

After Homebrew installation and "Next steps", run this from terminal:

brew install bitcoin

3️⃣ CREATE BLOCKS DIR

⚠️Skip this step if no external SSD.

After the bitcoin installation, create your bitcoin blocks directory on your external SSD (most Macs don't have enough storage on their internal SSDs. 1 TB free for comfort.) Name the folder bitcoin. If your external SSD volume name has a space, rename that, too. No spaces! In this guide, the external SSD has the name ord-dev!

4️⃣ CONFIGURE BITCOIN.CONF

Run these commands in Terminal:

mkdir ~/Library/Application\ support/Bitcoin

echo blocksdir=/Volumes/ord-dev/Bitcoin > ~/Library/Application\ Support/Bitcoin/bitcoin.conf
echo txindex=1 >> ~/Library/Application\ Support/Bitcoin/bitcoin.conf
echo server=1 >> ~/Library/Application\ Support/Bitcoin/bitcoin.conf
echo mempoolfullrbf=1 >> ~/Library/Application\ Support/Bitcoin/bitcoin.conf

echo blocksdir=/Volumes/ord-dev/Bitcoin\\ntxindex=1\\nserver=1\\n > ~/Library/Application\ support/Bitcoin/bitcoin.conf

(where the /ord-dev/Bitcoin part is the actual path to the SSD and folder you created above. CAREFUL MODIFYING THIS COMMAND, EVERY SPACE AND SLASH AND ~ IS NEEDED!)

⚠️ If you don't have an external drive, then skip the blocksdir line!

• txindex=1 If you want to be able to access any transaction with commands like gettransaction , you need to configure Bitcoin Core to build a complete transaction index, which can be achieved with the txindex option.
• server=1 tells bitcoin to accept JSON-RPC commands, so you can query it

Confirm all settings with:

cat ~/Library/Application\ Support/Bitcoin/bitcoin.conf

5️⃣ START/STOP BITCOIN SERVICE

In terminal:

brew services start bitcoin

and this if you want to stop it again (not yet)

brew services stop bitcoin

6️⃣ CONFIRM SETTINGS

In the debug.log file located in ~/Library/Application\ Support/Bitcoin/, look for lines similar to these:

2023-11-15T13:16:47Z Default data directory /Users/username/Library/Application Support/Bitcoin
2023-11-15T13:16:47Z Using data directory /Users/username/Library/Application Support/Bitcoin
2023-11-15T13:16:47Z Config file: /Users/username/Library/Application Support/Bitcoin/bitcoin.conf
2023-11-15T13:16:47Z Config file arg: blocksdir="/Volumes/ord-dev/Bitcoin"
2023-11-15T13:16:47Z Config file arg: server="1"
2023-11-15T13:16:47Z Config file arg: txindex="1"
2023-11-15T13:16:47Z Generated RPC authentication cookie /Users/username/Library/Application Support/Bitcoin/.cookie

⚠️ An easy way to monitor the file in Terminal is to use this command:

tail -F -n 10000 ~/Library/Application\ Support/Bitcoin/debug.log

These entries in the output confirm that the blocks dir and the configuration entries have been recognized and have taken effect. Pay attention to the cookie line. You'll need that later, so make sure you have it!

7️⃣ INITIAL BLOCK DOWNLOAD (aka BLOCKCHAIN SYNC)

The initial block download will generally take 1+ days, depending on factors like CPU/disk/network speed. As it progresses, you'll see lines like this in the debug.log file:

2023-02-22T15:18:23Z UpdateTip: new best=00000000000000000000e2319131e7e41d3b93e8b9086fc427f2ee9383aa2686 height=777656 version=0x20004000 log2_work=94.017345 tx=807469638 date='2023-02-21T14:40:00Z' progress=0.999679 cache=2.5MiB(18835txo)

The progress= entry tells you how far you are along. It will reach 1.000000 at completion of the initial block download and then you can leave bitcoin running as a service and proceed to the ord installation and configuration.

8️⃣ EXTRA: FINAL CONFIRMATION OF READINESS

Run this in terminal:

bitcoin-cli getindexinfo

You should see a response like this:

{
  "txindex": {
    "synced": true,
    "best_block_height": 839505
}

If it shows synced:false or the block height is not current, wait longer and run the command again. If it shows synced:true and current block height, proceed to ord installation!

9️⃣ EXTRA: Setting Up Bitcoin Core to Accept Remote Procedure Calls (RPC) from an External Host

Here are some tips for getting the bitcoin core node up and running and accepting RPC connections from external hosts. This is not an efficient setup in combination with ord (it should be much faster when everything runs on the same machine), but useful for other development tasks.

~/Library/Application\ Support/Bitcoin/bitcoin.conf (mac).
/bitcoin/.bitcoin/bitcoin.conf (linux)

server=1
rpcbind=0.0.0.0
rpcallowip=<your_network_range>
rpcport=8332
rpcauth=<username>:<hashed_password>
txindex=1
mempoolfullrbf=1

server=1

This tells tells Bitcoin to accept JSON-RPC commands.

rpcbind=0.0.0.0

This will tell Bitcoin to listen an every available network interface. If you would like to only accept connections on a specific network interface, replace 0.0.0.0 with the IP of your desired network interface.

rpcallowip=<your_network_range>

With rpcallowip you can either specify an IP range in CIDR format, or specify the rpcallowip option multiple times with distinct IP addresses that you want to allow connections from.

Note: Wildcards are no longer supported. You need to use subnets now. To allow everything that would be 0.0.0.0/0 (ipv4) or ::/0 (ipv6). Of course, this is not save to expose to untrusted networks such as the public internet!

rpcport=8332

This sets the port that Bitcoin will listen on for RPC connections. Port 8332 is the default.

rpcauth=:<hashed_password>

This configuration sets a username and password (hashed) to be used for authenticating RPC requests. Bitcoin Core RPC Auth Config Generator is a useful tool for generating the hashed passwords.

txindex=1

With txindex=1 Bitcoin Core maintains an index of all transactions that have ever happened, which you can query using the remote procedure call (RPC) method getrawtransaction or the RESTful API call get-tx .

Next, restart the bitcoind service!

Then, on the machine that you’ll be making RPC requests from, make a test request using curl:

curl -f --user <username> --data-binary \
    '{"method":"getblockhash","params":[0],"id":1}' \
    -H 'content-type: text/plain;' http://<hostname>:<port>/

In the above request, replace the following values:

• <username> – Replace this with the value you specified for rpcuser in your bitcoin.conf file.
• <hostname>:<port> - Replace <hostname> with the IP address or hostname of your Bitcoin server and <port> with the value you specified for rpcport in your bitcoin.conf file Hint: execute ifconfig to figure out your IP address.

If everything is set up correctly, after running the curl command, you should be prompted for your RPC password and Bitcoin will respond with a valid result.

1_README_ord.md

1️⃣ INSTALL ORD

Run this command in terminal:

brew install ord

Confirm success by typing this in terminal:

ord --version

You should get a response like this (or a higher version):

ord 0.20.0

2️⃣ CREATE ORD INDEX

⚠️ If you don't have an internal SSD (you have an internal spinning disk) this may not work well. Seek assistance to relocate your index file with the --index switch. Doing so will change all following ord commands in this guide, as well.

We will create a full-blown ord index with sats and runes on your internal SSD. Run this command:

ord --index-runes --index-sats --index ~/ordindex.redb  server

If all's well you'll see an indexing progress bar. It will start fast and slow down considerably. If it completes, great -- often it doesn't if your computer's resources are constrained. If it slows or appears to stop--WAIT LONGER. A trick that seems to work if it completely bombs out at the end or stops for many hours, is to press ctrl-c (only once!) when it's a few blocks from completing, then give it time to exit gracefully, reboot and run it again. Repeat until successful.

--index-sats

Track location of all satoshis. Note: This tracks the current location of the sat, not the history. Spent outputs won't show sat-ranges.

--index-addresses

Track unspent output addresses. This allows you to view the contents of an address within ord.

JUST DOWNLOAD AN ORD INDEX

Tired of waiting? Ok, there are Ordinals Index files pre-built by Greg. These are the pre-built index.redb files, ready for download:

https://ordstuff.info/

Thanks Greg! 🙏

Yeah, that's just the .torrent file. You need to plug that into a torrent app to download the multi-gigabyte .redb.gz file.

Two possible clients for Mac:

• Transmission
• qbittorrent

2_README_bitcoin_linux.md

Ord Guide for Linux

Main source for this: Homebrew appreciation thread for Bitcoin and ord on Mac and Linux by ETS – This whole guide is a blatant copy & paste, I deserve zero credits!

This guide assumes a 2TB primary SSD and 64GB of Ram. Even machines with 32GB+ sometimes struggle these days. Go for 64GB! I did this installation on a "debian 12 (bookworm) - minimal" VPS.

0️⃣ Only if required: Installing Curl on Debian

First apply patches for your system:

sudo apt update && sudo apt upgrade

Install curl (necessary) and other build tools:

apt install build-essential procps curl file git

curl --version

1️⃣ INSTALL HOMEBREW

Install Homebrew from http://brew.sh/, the webpage should tell you to execute:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

If you get the error: "Don't run this as root!" then you are logged in as "root". The issue here is that Homebrew does not recommend or allow installation as the root user for security reasons. Instead, it should be installed under a regular user account with sudo privileges.

Here's how you can resolve the issue:

Create a new user (if you don't already have one) and give it sudo privileges. Here's how to do that for a user called ord-dev

adduser ord-dev

Follow the prompt to set up a password. Add the user to the sudo group:

usermod -aG sudo ord-dev

Switch to the new user:

su - ord-dev

Now try again:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

⚠️ When installation completes, follow the steps listed in "Next steps" to add Homebrew to your path.

2️⃣ INSTALL BITCOIN

After Homebrew installation and "Next steps", run this from terminal:

brew install bitcoin

3️⃣ CONFIGURE BITCOIN.CONF

Run these commands in Terminal:

mkdir ~/.bitcoin/bitcoin.conf

echo txindex=1 >> ~/.bitcoin/bitcoin.conf
echo server=1 >> ~/.bitcoin/bitcoin.conf
echo mempoolfullrbf=1 >> ~/.bitcoin/bitcoin.conf

• txindex=1 If you want to be able to access any transaction with commands like gettransaction , you need to configure Bitcoin Core to build a complete transaction index, which can be achieved with the txindex option.
• server=1 tells bitcoin to accept JSON-RPC commands, so you can query it

Confirm all settings with:

cat ~/.bitcoin/bitcoin.conf

4️⃣ START/STOP BITCOIN SERVICE

In terminal:

brew services start bitcoin

and this if you want to stop it again (not yet)

brew services stop bitcoin

If this works you are lucky and can skip section 5.

5️⃣ TROUBLESHOOTING (for Debian)

How to fix this error:

Failed to connect to bus: No medium found
Error: Failure while executing; `/usr/bin/systemctl --user daemon-reload` exited with 1.

This error occurs because systemctl (used by brew services) requires systemd to be set up for user sessions, which is not always enabled by default in systems like Debian, especially in minimal or server installations. Switching to systemctl for managing services like bitcoin and ord is a more sustainable and reliable solution on Debian. Homebrew works well for package management, but it struggles with service management on Linux, particularly in systems like Debian that don’t fully support systemctl --user by default.

sudo nano /etc/systemd/system/bitcoind.service

Add the following content:

[Unit]
Description=Bitcoin Daemon
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/home/linuxbrew/.linuxbrew/opt/bitcoin/bin/bitcoind
User=ord-dev
Restart=on-failure
Type=simple

[Install]
WantedBy=multi-user.target

Then execute the following commands to start the daemon:

sudo systemctl daemon-reload
sudo systemctl enable bitcoind
sudo systemctl start bitcoind
sudo systemctl status bitcoind

While we are here, this is a working the configution for ord (that was installed via homebrew):

sudo nano /etc/systemd/system/ord.service

Add the following content:

[Unit]
Description=Ord Daemon
After=network.target

[Service]
AmbientCapabilities=CAP_NET_BIND_SERVICE
Environment=RUST_BACKTRACE=1
Environment=RUST_LOG=info
ExecStart=/home/linuxbrew/.linuxbrew/bin/ord \
  --index-runes \
  --index-sats \
  --index-addresses \
  server \
  --http
User=ord-dev
Restart=on-failure

[Install]
WantedBy=multi-user.target

AmbientCapabilities=CAP_NET_BIND_SERVICE: This grants the ord service the specific capability to bind to privileged ports (like port 80) without running as root. The default location of the index is: ~/.local/share/ord.

Run the ord daemon permanently:

sudo systemctl daemon-reload
sudo systemctl enable ord
sudo systemctl start ord
sudo systemctl status ord

To view the full logs for your ord service managed by systemd, you can use journalctl, which collects logs for all systemd-managed services. This will show the complete log history:

sudo journalctl -u ord

Or follow the logs in real-time (like tail -f):

sudo journalctl -u ord -f

To delete logs older than a specific time period, such as 1 week:

sudo journalctl --vacuum-time=1w

6️⃣ CONFIRM SETTINGS

In the debug.log file located in ~/.bitcoin, look for lines similar to these:

2024-09-24T19:28:09Z Default data directory /home/ord-dev/.bitcoin
2024-09-24T19:28:09Z Using data directory /home/ord-dev/.bitcoin
2024-09-24T19:28:09Z Config file: /home/ord-dev/.bitcoin/bitcoin.conf
2024-09-24T19:28:09Z Config file arg: server="1"
2024-09-24T19:28:09Z Config file arg: txindex="1"
2024-09-24T19:28:09Z Generated RPC authentication cookie /home/ord-dev/.bitcoin/.cookie

⚠️ An easy way to monitor the file in Terminal is to use this command:

tail -F -n 10000 ~/.bitcoin/debug.log

These entries in the output confirm that the configuration entries have been recognized and have taken effect. Pay attention to the cookie line. You'll need that later, so make sure you have it!

7️⃣ INITIAL BLOCK DOWNLOAD (aka BLOCKCHAIN SYNC)

The initial block download will generally take 1+ days, depending on factors like CPU/disk/network speed. As it progresses, you'll see lines like this in the debug.log file:

2023-02-22T15:18:23Z UpdateTip: new best=00000000000000000000e2319131e7e41d3b93e8b9086fc427f2ee9383aa2686 height=777656 version=0x20004000 log2_work=94.017345 tx=807469638 date='2023-02-21T14:40:00Z' progress=0.999679 cache=2.5MiB(18835txo)

The progress= entry tells you how far you are along. It will reach 1.000000 at completion of the initial block download and then you can leave bitcoin running as a service and proceed to the ord installation and configuration.

7️⃣ EXTRA: FINAL CONFIRMATION OF READINESS

Run this in terminal:

bitcoin-cli getindexinfo

You should see a response like this:

{
  "txindex": {
    "synced": true,
    "best_block_height": 839505
}

If it shows synced:false or the block height is not current, wait longer and run the command again. If it shows synced:true and current block height, proceed to ord installation!

4_README_esplora.md

How to run the explorer for Bitcoin mainnet

esplora is just the web ui frontend, you also need to setup the (forked) electrs backend for indexing and for providing the HTTP API that esplora queries.

electrs can index the bitcoin block chain using two methods: by reading the blk files directly out of disk, or by querying for blocks using the bitcoind rpc. The first method is significantly faster, but requires electrs to have filesystem access to the bitcoin datadir, which would typically mean running them on the same server (you could technically do this remotely but you'll lose most of the performance gain, so not much point in doing that). The second method can work if you have two separate servers, but I wouldn't recommend it (would be painfully slow).

https://bitcoin.stackexchange.com/a/91859

Without Docker

brew install rust

To setup electrs, install Rust and:

$ sudo apt install clang cmake # required for building rust-rocksdb $ git clone https://github.com/blockstream/electrs && cd electrs $ git checkout new-index $ cargo run --release --bin electrs -- -vvv --daemon-dir ~/.bitcoin

With Docker (runs own bitcoin node, will index again!!!)

docker run -p 50001:50001 -p 8080:80 \
           --volume $PWD/data_bitcoin_mainnet:/data \
           --rm -i -t esplora \
           bash -c "/srv/explorer/run.sh bitcoin-mainnet explorer"

For my drive and for the pre-build imgage:

mkdir ~/Library/Application\ Support/Bitcoin/esplora-mainnet

docker run -p 50001:50001 -p 8080:80 \
           --volume ~/Library/Application\ Support/Bitcoin/esplora-mainnet:/data \
           --rm -i -t blockstream/esplora \
           bash -c "/srv/explorer/run.sh bitcoin-mainnet explorer"

5_README_extra.md

disablesleep 1

You don’t want your MacBook to sleep when you close the lid?

sudo pmset -a disablesleep 1

That should stop your Mac sleeping.