New explorer (#4292)

## Motivation

Linera already has a block explorer but that's based on the node service
and GraphQL subscriptions. Since we are doubling down on the block
exporter and have an indexer destination (that pushes data to an SQL
database) we should build an indexer on top of that.

## Proposal

Add a simple block explorer that connects to the SQLite database and
displays blocks.

To test:
1. Build docker images (in `/docker` directory run
`./make-all-build.sh`).
2. Run the setup (in `/docker` dir run `./make-all-up.sh`).

You have a fully-functional setup now consisting of:
- linera storage service
- linera network (with 1 validator) and a faucet
- linera exporter
- linera indexer (SQLite db)
- linera explorer

To test further, you can deploy apps to it as usual to the local network
(faucet is on 8080 port by default).

<img width="1156" height="716" alt="Screenshot 2025-08-05 at 15 18 51"
src="https://github.com/user-attachments/assets/f7688196-0f90-4deb-8a86-83c56dc887e9"
/>
<img width="1142" height="655" alt="Screenshot 2025-08-05 at 15 19 11"
src="https://github.com/user-attachments/assets/8ed2a0a8-1b50-4af9-8277-72940e7b6aac"
/>
<img width="1192" height="644" alt="Screenshot 2025-08-05 at 15 19 24"
src="https://github.com/user-attachments/assets/76ff4e4d-7fd4-420b-80cf-4f4f09319a80"
/>

(This PR was ~~almost entirely~~ (not anymore – a lot of back-and-forth
and watching over his shoulder) written by Claude Code)

## Test Plan

Manual.

## Release Plan

- Nothing to do

## Links

- [reviewer
checklist](https://github.com/linera-io/linera-protocol/blob/main/CONTRIBUTING.md#reviewer-checklist)

Author: deuszx

docker/.env.indexer-test

@@ -0,0 +1,16 @@
+# Storage service configuration
+LINERA_STORAGE_SERVICE_PORT=1235
+
+# Indexer configuration  
+INDEXER_PORT=8081
+INDEXER_DATABASE_PATH=/data/indexer.db
+
+# Block exporter configuration
+BLOCK_EXPORTER_PORT=8882
+METRICS_PORT=9091
+
+# Network configuration
+FAUCET_PORT=8080
+
+# Docker image
+LINERA_INDEXER_IMAGE=linera-all-test

docker/.env.local

@@ -0,0 +1,16 @@
+# Storage service configuration
+LINERA_STORAGE_SERVICE_PORT=1235
+
+# Indexer configuration  
+INDEXER_PORT=8081
+INDEXER_DATABASE_PATH=/data/indexer.db
+
+# Block exporter configuration
+BLOCK_EXPORTER_PORT=8882
+METRICS_PORT=9091
+
+# Network configuration
+FAUCET_PORT=8080
+
+# Docker image
+LINERA_INDEXER_IMAGE=linera-all-test

docker/Dockerfile.explorer

@@ -0,0 +1,71 @@
+# Multi-stage build for Linera Explorer
+# Stage 1: Build the frontend
+FROM node:18-alpine AS frontend-builder
+
+WORKDIR /app
+
+# Copy package files
+COPY linera-explorer-new/package*.json ./
+COPY linera-explorer-new/tsconfig*.json ./
+COPY linera-explorer-new/vite.config.ts ./
+COPY linera-explorer-new/tailwind.config.js ./
+COPY linera-explorer-new/postcss.config.js ./
+COPY linera-explorer-new/index.html ./
+
+# Install all dependencies (including dev dependencies for build)
+RUN npm ci
+
+# Copy source code
+COPY linera-explorer-new/src ./src
+
+# Build frontend
+RUN npm run build
+
+# Stage 2: Setup backend dependencies
+FROM node:18-alpine AS backend-builder
+
+WORKDIR /app
+
+# Copy backend files
+COPY linera-explorer-new/server ./server
+COPY linera-explorer-new/package*.json ./
+
+# Install backend dependencies (including better-sqlite3)
+RUN npm ci --only=production
+
+# Stage 3: Production runtime
+FROM node:18-alpine
+
+# Install sqlite3 for database operations
+RUN apk add --no-cache sqlite
+
+WORKDIR /app
+
+# Copy built frontend from stage 1
+COPY --from=frontend-builder /app/dist ./dist
+
+# Copy backend and dependencies from stage 2
+COPY --from=backend-builder /app/server ./server
+COPY --from=backend-builder /app/node_modules ./node_modules
+COPY --from=backend-builder /app/package.json ./package.json
+
+# Create data directory for database
+RUN mkdir -p /data
+
+# Copy startup script
+COPY docker/explorer-entrypoint.sh ./entrypoint.sh
+RUN chmod +x ./entrypoint.sh
+
+# Expose ports
+EXPOSE 3001 3002
+
+# Set environment variables
+ENV NODE_ENV=production
+ENV DB_PATH=/data/indexer.db
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
+    CMD wget --no-verbose --tries=1 --spider http://localhost:3002/api/health || exit 1
+
+# Start both frontend and backend
+CMD ["sh", "./entrypoint.sh"]

docker/Dockerfile.indexer-test

@@ -120,21 +120,22 @@ COPY \
 FROM builder$copy AS binaries
 
 # Setup running environment for container
-FROM debian:latest
+FROM debian:bookworm-slim
 
 ARG git_commit
 LABEL git_commit=$git_commit
 
 ARG build_date
 LABEL build_date=$build_date
 
-RUN apt-get update && apt-get install -y \
+RUN apt-get update && apt-get install --no-install-recommends -y \
     ca-certificates \
     openssl \
     pkg-config \
     protobuf-compiler \
     clang \
     netcat-openbsd
+RUN apt-get clean && rm -rf /var/lib/apt/lists/*
 RUN update-ca-certificates
 
 ARG target

docker/README.indexer-test.md

@@ -19,14 +19,14 @@ The setup includes the following services in startup order:
 
 ```bash
 cd docker
-docker build -f Dockerfile.indexer-test -t linera-all-test ..
+./make-all-build.sh
 ```
 
 ### 2. Start the Services
 
 ```bash
 # in /docker directory
-docker-compose -f docker-compose.indexer-test.yml --env-file ../.env.indexer-test up
+./make-all-up.sh
 ```
 
 ### 3. Verify Services are Running
@@ -37,6 +37,13 @@ docker-compose -f docker-compose.indexer-test.yml --env-file ../.env.indexer-tes
     - Metrics `curl http://localhost:9091/metrics`
 - Faucet: `curl http://localhost:8080`
 
+
+### 4. Stop the services
+```bash
+# in /docker directory
+./make-all-down.sh
+```
+
 ## Configuration
 
 ### Environment Variables

docker/docker-compose.indexer-test.yml

@@ -74,7 +74,7 @@ services:
     networks:
       - linera-network
 
-  # 4. Network (Validator + Faucet) - starts last
+  # 4. Network (Validator + Faucet) - starts after block exporter
   linera-network:
     image: "${LINERA_INDEXER_IMAGE:-linera-all-test}"
     container_name: linera-network
@@ -91,9 +91,16 @@ services:
       --exporter-address linera-block-exporter
       --exporter-port ${BLOCK_EXPORTER_PORT:-8882}"
     environment:
+      - RUST_LOG=linera=info
       - LINERA_STORAGE_SERVICE_PORT=${LINERA_STORAGE_SERVICE_PORT:-1235}
       - FAUCET_PORT=${FAUCET_PORT:-8080}
       - BLOCK_EXPORTER_PORT=${BLOCK_EXPORTER_PORT:-8882}
+    healthcheck:
+      test: ["CMD-SHELL", "nc -z localhost ${FAUCET_PORT:-8080}"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
+      start_period: 20s
     volumes:
       - network-data:/data
     depends_on:
@@ -102,6 +109,32 @@ services:
     networks:
       - linera-network
 
+  # 5. Explorer - starts last after all services are ready
+  linera-explorer:
+    image: "${LINERA_EXPLORER_IMAGE:-linera-explorer-new}"
+    container_name: linera-explorer
+    ports:
+      - "${EXPLORER_FRONTEND_PORT:-3001}:3001"
+      - "${EXPLORER_API_PORT:-3002}:3002"
+    environment:
+      - NODE_ENV=production
+      - DB_PATH=/data/indexer.db
+      - EXPLORER_FRONTEND_PORT=${EXPLORER_FRONTEND_PORT:-3001}
+      - EXPLORER_API_PORT=${EXPLORER_API_PORT:-3002}
+    volumes:
+      - ./indexer-data:/data:ro
+    depends_on:
+      linera-indexer:
+        condition: service_healthy
+    healthcheck:
+      test: ["CMD-SHELL", "wget --no-verbose --tries=1 --spider http://localhost:${EXPLORER_API_PORT:-3002}/api/health || exit 1"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 30s
+    networks:
+      - linera-network
+
 volumes:
   indexer-data:
     driver: local

docker/explorer-entrypoint.sh

@@ -0,0 +1,40 @@
+#!/bin/sh
+set -e
+
+echo "Starting Linera Explorer..."
+
+# Wait for database file to exist (created by indexer)
+echo "Waiting for indexer database..."
+while [ ! -f "${DB_PATH:-/data/indexer.db}" ]; do
+    echo "Database not found at ${DB_PATH:-/data/indexer.db}, waiting..."
+    sleep 2
+done
+
+echo "Database found, starting services..."
+
+# Start the API server in the background
+echo "Starting API server on port 3002..."
+cd /app && node server/index.js &
+API_PID=$!
+
+# Wait a moment for API to start
+sleep 3
+
+# Start frontend server (serve static files)
+echo "Starting frontend server on port 3001..."
+npx serve -s dist -l 3001 &
+FRONTEND_PID=$!
+
+# Function to handle shutdown
+shutdown() {
+    echo "Shutting down services..."
+    kill $API_PID $FRONTEND_PID 2>/dev/null || true
+    wait $API_PID $FRONTEND_PID 2>/dev/null || true
+    exit 0
+}
+
+# Handle signals
+trap shutdown SIGTERM SIGINT
+
+# Wait for either process to exit
+wait $API_PID $FRONTEND_PID

docker/make-all-build.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+# NOTE: This script assumes to be called from within the `/docker` directory.
+echo "Building linera images..."
+docker build -f ./Dockerfile.indexer-test -t linera-all-test ..
+
+echo "Building linera explorer image..."
+docker build -f ./Dockerfile.explorer -t linera-explorer-new ..
+
+
+echo "Done building images"

docker/make-all-down.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+
+docker-compose -f ./docker-compose.indexer-test.yml down --volumes --remove-orphans
+
+# Removing data directories so that the next run starts with a clean state
+echo "Removing exporter data..."
+rm -rf ./exporter-data/
+echo "Removing indexer data..."
+rm -rf ./indexer-data/
+echo "All data removed"

docker/make-all-up.sh

@@ -0,0 +1,9 @@
+#!/bin/bash
+
+# Removing data directories so that the next run starts with a clean state
+echo "Removing exporter data..."
+rm -rf ./exporter-data/
+echo "Removing indexer data..."
+rm -rf ./indexer-data/
+echo "All data removed"
+docker-compose -f ./docker-compose.indexer-test.yml up --force-recreate --remove-orphans