# Oxigraph Installation & Setup Status

**Date**: November 22, 2025  
**Status**: ⚠️ **ISSUE ENCOUNTERED** - macOS ARM compatibility  

---

## Installation Summary

✅ **Oxigraph v0.5.2 Downloaded Successfully**
- Binary location: `~/.local/bin/oxigraph_server`
- Platform: macOS ARM64 (aarch64_apple)
- Source: https://github.com/oxigraph/oxigraph/releases/tag/v0.5.2

---

## Issue Encountered

❌ **Runtime Error on macOS ARM**:

```
thread 'main' panicked at lib/oxigraph/src/storage/rocksdb_wrapper.rs:332:56:
called `Result::unwrap()` on an `Err` value: TryFromIntError(())
```

**Cause**: Appears to be a bug in Oxigraph v0.5.2 with RocksDB on macOS ARM architecture.

**GitHub Issue**: Likely related to https://github.com/oxigraph/oxigraph/issues (check for recent ARM-related issues)

---

## Workarounds

### Option 1: Use In-Memory Mode (Recommended for Development)

The server supports in-memory storage by omitting the `--location` flag:

```bash
#!/bin/bash
# In-memory Oxigraph (data not persisted)
export PATH="$HOME/.local/bin:$PATH"

oxigraph_server serve \
  --bind "127.0.0.1:7878" \
  --cors
```

**Pros**:
- No database corruption issues
- Fast startup
- Good for development/testing

**Cons**:
- Data lost on restart
- Must reload data each time

### Option 2: Try Older Version

Download v0.4.8 or earlier (may not have ARM builds):
- Check: https://github.com/oxigraph/oxigraph/releases/tag/v0.4.8

### Option 3: Use Docker

Run Oxigraph in Docker (Linux container, no ARM issues):

```bash
docker run -d \
  -p 7878:7878 \
  -v $(pwd)/data/oxigraph-db:/data \
  ghcr.io/oxigraph/oxigraph:v0.5.2 \
  serve --location /data --bind 0.0.0.0:7878
```

### Option 4: Alternative Triplestores

If Oxigraph continues to have issues:
- **Apache Jena Fuseki** - Very stable, Java-based
- **Blazegraph** - Fast, used by Wikidata
- **RDF4J Server** - Lightweight, good for testing

---

## Recommended Approach for Task 7

**For initial development**, use **Option 1** (in-memory mode):

1. Start in-memory Oxigraph server
2. Load sample data on each startup
3. Test SPARQL client implementation
4. Once code is working, switch to persistent storage (Docker or fix ARM issue)

**Updated Scripts**:

`scripts/start-oxigraph-memory.sh`:
```bash
#!/bin/bash
# Start Oxigraph in-memory mode (development)

export PATH="$HOME/.local/bin:$PATH"

echo "🚀 Starting Oxigraph Server (In-Memory Mode)..."
echo "🌐 Endpoint: http://127.0.0.1:7878"
echo "⚠️  Data will be lost on restart"
echo ""

oxigraph_server serve --bind "127.0.0.1:7878" --cors
```

`scripts/load-sample-data-memory.sh`:
```bash
#!/bin/bash
# Load data into in-memory Oxigraph
# Run this AFTER starting the server

sleep 2  # Wait for server startup

echo "📥 Loading sample data..."
curl -X POST \
  -H 'Content-Type: application/n-triples' \
  --data-binary '@data/sample-rdf/dutch-heritage-institutions.nt' \
  http://127.0.0.1:7878/store

echo "✅ Data loaded!"
```

---

## Next Steps

1. **Continue with Task 7 implementation** using in-memory mode
2. **Document the workaround** in PHASE3_TASK7_PLAN.md
3. **Implement SPARQL client** (independent of storage mode)
4. **Test with in-memory data**
5. **Investigate ARM fix** or switch to Docker for production

---

## Scripts Created

- ✅ `scripts/install-oxigraph.sh` - Download and install binary
- ✅ `scripts/start-oxigraph.sh` - Start server (currently broken on ARM)
- ✅ `scripts/load-sample-data.sh` - Load RDF data via HTTP
- ⏳ **TODO**: Create in-memory variants of startup/loading scripts

---

## Sample Data Ready

✅ `data/sample-rdf/dutch-heritage-institutions.nt` created with 6 institutions:
- Amsterdam Museum
- Rijksmuseum
- Koninklijke Bibliotheek (National Library)
- Stadsarchief Amsterdam (City Archives)
- Van Gogh Museum
- Mauritshuis

**Data includes**:
- Institution types (Museum, Library, Archive)
- Names (multilingual)
- Descriptions
- URLs
- Founding dates
- Addresses
- Wikidata links

---

## Conclusion

**Status**: Step 1 (Install Oxigraph) **PARTIALLY COMPLETE** ⚠️

- ✅ Binary installed
- ✅ Scripts created
- ✅ Sample data prepared
- ❌ Persistent storage not working on macOS ARM
- ✅ **Workaround available** (in-memory mode)

**Decision**: **Proceed with Task 7** using in-memory Oxigraph for development. Address persistence later with Docker or upstream bug fix.

---

**Updated**: November 22, 2025  
**Estimated Delay**: ~30 minutes (workaround implementation)  
**Impact**: Minimal - in-memory mode sufficient for development