Skip to content

improve readme and start script #78

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Ryun1 merged 1 commit into from
Dec 13, 2025
Merged

improve readme and start script #78

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
126 changes: 9 additions & 117 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,12 +20,6 @@ Install docker desktop for your operating system.
If you are using Apple silicon (M1, M2, M3 processor) make sure you have Rosetta
enabled via Docker desktop settings.

### Visual Studio Code

Install VSCode so we can more easily navigate directories, and inspect files.

- <https://code.visualstudio.com/>

### Mac Specific Prerequisites

1. xcode tools.
Expand Down Expand Up @@ -96,7 +90,7 @@ chmod +x ./start-node.sh ./stop-nodes.sh ./scripts/*

### Start node

We have a script that:
We have a start script which:

- pulls the latest testnet node configs
- pulls the Cardano node docker image
Expand Down Expand Up @@ -144,7 +138,7 @@ wsl
In your second terminal execute:

```bash
./scripts/node-query-tip.sh
./scripts/query/tip.sh
```

For a fully synced node the terminal should return, with `syncProgress` of `100.00`.
Expand Down Expand Up @@ -185,7 +179,7 @@ This script will stop your Cardano node, remember to run this when you are done
In your second terminal execute:

```bash
./stop-docker.sh
./stop-nodes.sh
```

## Doing Stuff
Expand Down Expand Up @@ -249,129 +243,27 @@ Make sure you have a node running for these.

## Using Multiple Nodes and External Nodes

This toolkit supports connecting to multiple Cardano nodes simultaneously - both Docker containers and external nodes running outside of Docker. You can run scripts against different networks and nodes at the same time.
This toolkit supports connecting to multiple Cardano nodes simultaneously - both Docker containers and external nodes running outside of Docker.
You can run scripts against different networks and nodes at the same time.

### External Node Configuration

External nodes use environment variables `CARDANO_NODE_SOCKET_PATH` and `CARDANO_NODE_NETWORK_ID`. You can configure these through the `start-node.sh` script, which will prompt you for the values and confirm them before use.
External nodes use environment variables `CARDANO_NODE_SOCKET_PATH` and `CARDANO_NODE_NETWORK_ID`.
You can check these through the `start-node.sh` script,
which will prompt you for the values and confirm them before use.

**Important:** Only one external node connection is supported at a time. For multiple external nodes, switch environment variables between script executions.

#### Setting Up External Node

Use the `start-node.sh` script to configure:

```bash
./start-node.sh
# Select: "Configure connection to an external node via socket file"
# Enter socket path and network ID
# Confirm the values
```

Or set environment variables directly:

```bash
export CARDANO_NODE_SOCKET_PATH="/path/to/node.socket"
export CARDANO_NODE_NETWORK_ID=1 # 1=preprod, 2=preview, 4=sanchonet

# Run scripts
./scripts/query/tip.sh
```

#### Network Magic Numbers

- **preprod**: Network ID `1`
- **preview**: Network ID `2`
- **sanchonet**: Network ID `4`

### Multiple Docker Containers

When multiple Docker containers are running, the toolkit will:

- **Automatically select** the only container if only one is running
- **Prompt you to choose** if multiple containers are running (interactive mode)
- **Use the first container** if running non-interactively (no TTY)

To avoid prompts, specify the container name:

```bash
CARDANO_CONTAINER_NAME="node-preprod-10.5.3-container" ./scripts/query/tip.sh
```

### Single Node Configuration (Backward Compatible)

For backward compatibility, you can still use the old single-node format:

```json
{
"socket_path": "/path/to/your/node.socket",
"network": "preprod",
"network_id": 1,
"mode": "external"
}
```

### Requirements

- **Local cardano-cli**: When using external node mode, you must have `cardano-cli` installed locally and available in your PATH
- **Network restriction**: Mainnet connections via external sockets are **not allowed** for security reasons. Only testnet networks (preprod, preview, sanchonet) are supported
- **Socket file**: The socket file must be accessible and the node must be running

### Network Magic Numbers

- **preprod**: Network ID `1`
- **preview**: Network ID `2`
- **sanchonet**: Network ID `4`
- **mainnet**: Network ID `764824073` (blocked for external nodes, allowed in Docker mode)

### Example: Running Scripts Against Multiple Networks

```bash
# Terminal 1: Query preprod via external node
CARDANO_NODE_SOCKET_PATH="/path/to/preprod.socket" CARDANO_NODE_NETWORK_ID=1 ./scripts/query/tip.sh

# Terminal 2: Query preview via external node (switch env vars)
CARDANO_NODE_SOCKET_PATH="/path/to/preview.socket" CARDANO_NODE_NETWORK_ID=2 ./scripts/query/tip.sh

# Terminal 3: Use Docker container for mainnet
CARDANO_CONTAINER_NAME="node-mainnet-10.5.3-container" ./scripts/query/tip.sh
```

### Node Selection Priority

The toolkit uses the following priority order:

1. `CARDANO_NODE_SOCKET_PATH` + `CARDANO_NODE_NETWORK_ID` - External node (environment variables)
2. `CARDANO_CONTAINER_NAME` - Direct container name specification (for Docker mode)
3. Docker mode with container selection - Default fallback

**Note:** External nodes require both `CARDANO_NODE_SOCKET_PATH` and `CARDANO_NODE_NETWORK_ID` to be set. Use the `start-node.sh` script to configure and confirm these values.

### Version Check

When using external node mode, the toolkit will automatically check and display your local `cardano-cli` version and which node is being used. If `cardano-cli` is not found in PATH, you'll receive a warning.

## Common Error Messages

### Docker desktop application not open

```bash
Cannot connect to the Docker daemon at unix:///Users/XXXX/.docker/run/docker.sock. Is the docker daemon running?
```

**Fix:** Open docker desktop

### Mainnet connection blocked

```bash
Error: Mainnet connections are not allowed. Please use testnet networks (preprod, preview, sanchonet) only.
```

**Fix:** This error appears when attempting to connect to mainnet via external socket. Use Docker mode for mainnet, or switch to a testnet network.

### cardano-cli not found

```bash
Warning: cardano-cli not found in PATH. External node mode requires cardano-cli to be installed locally.
```

**Fix:** Install `cardano-cli` locally and ensure it's in your PATH when using external node mode.
23 changes: 23 additions & 0 deletions start-node.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,29 @@ BLUE='\033[0;34m'
CYAN='\033[0;36m'
NC='\033[0m' # No color

# Function to check if Docker is running
check_docker_running() {
echo -e "${CYAN}Checking if Docker is running...${NC}"

if ! command -v docker >/dev/null 2>&1; then
echo -e "${RED}Error: Docker is not installed.${NC}"
echo -e "${YELLOW}Please install Docker Desktop from: https://www.docker.com/products/docker-desktop${NC}"
exit 1
fi

if ! docker info >/dev/null 2>&1; then
echo -e "${RED}Error: Docker is installed but not running.${NC}"
echo -e "${YELLOW}Please start Docker Desktop and try again.${NC}"
exit 1
fi

echo -e "${GREEN}Docker is running.${NC}"
echo
}

# Check Docker before proceeding
check_docker_running

# ASCII Art Welcome Message
echo -e "${CYAN}"
echo " "
Expand Down