Skip to content

03-quick-start.md

Latest commit

 

History

History
199 lines (152 loc) · 5.56 KB

03-quick-start.md

File metadata and controls

199 lines (152 loc) · 5.56 KB

EntityDB Quick Start Guide

Version: v2.32.2 | Last Updated: 2025-06-16 | Status: GUIDANCE

Welcome to EntityDB! This guide will get you up and running with EntityDB v2.32.2 in just a few minutes.

⚠️ Critical: v2.29.0+ includes major authentication changes. User credentials are now embedded in user entities. All users from previous versions must be recreated.

Prerequisites

  • Git
  • Go 1.19+ (for building from source)
  • Linux/macOS environment
  • jq (for JSON parsing in examples)

Installation

1. Clone Repository

git clone https://git.home.arpa/itdlabs/entitydb.git
cd entitydb

2. Build Server

cd src
make
cd ..

3. Verify Installation

./bin/entitydb --version
# Should output: EntityDB v2.32.2

Starting EntityDB

Start the Server

# Start server daemon with SSL enabled (default)
./bin/entitydbd.sh start

# Check server status
./bin/entitydbd.sh status

# View server logs
./bin/entitydbd.sh logs

# Stop server
./bin/entitydbd.sh stop

Server Configuration

  • URL: https://localhost:8085 (SSL enabled by default)
  • Data: Stored in /opt/entitydb/var/
  • Config: /opt/entitydb/share/config/entitydb.env

SSL Note: EntityDB uses SSL by default. The -k flag in curl commands bypasses certificate verification for development.

Default Admin Access

EntityDB automatically creates a default admin user on first startup:

  • Username: admin
  • Password: admin
  • Roles: admin, user

Security: Change the default password immediately in production!

Your First API Calls

1. Login and Get Token

TOKEN=$(curl -s -k -X POST https://localhost:8085/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin"}' | jq -r '.token')

echo "Token: $TOKEN"

2. Create Your First Entity

curl -k -X POST https://localhost:8085/api/v1/entities/create \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "my_first_document",
    "tags": ["type:document", "status:draft", "category:tutorial"],
    "content": "VGhpcyBpcyBteSBmaXJzdCBFbnRpdHlEQiBkb2N1bWVudCE="
  }'

3. List All Entities

curl -k -X GET "https://localhost:8085/api/v1/entities/list" \
  -H "Authorization: Bearer $TOKEN"

4. Query by Tag

curl -k -X GET "https://localhost:8085/api/v1/entities/list?tag=type:document" \
  -H "Authorization: Bearer $TOKEN"

5. Get Specific Entity

curl -k -X GET "https://localhost:8085/api/v1/entities/get?id=my_first_document" \
  -H "Authorization: Bearer $TOKEN"

6. Update Entity

curl -k -X PUT "https://localhost:8085/api/v1/entities/update?id=my_first_document" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": ["type:document", "status:published", "category:tutorial"],
    "content": "VXBkYXRlZCBmaXJzdCBFbnRpdHlEQiBkb2N1bWVudCE="
  }'

Web Dashboard

Access the EntityDB dashboard at: https://localhost:8085

The dashboard provides:

  • Entity browser and search
  • Real-time metrics and monitoring
  • System health status
  • Administrative tools

Core Concepts

Entities

Everything in EntityDB is an entity with:

  • ID: Unique identifier
  • Tags: Timestamped metadata
  • Content: Binary data (auto-chunked for large files)

Tags

Hierarchical namespace system:

type:document          # Entity classification
status:published       # Entity state  
category:tutorial      # Custom metadata
rbac:role:admin       # Access control

Temporal Storage

All tags are timestamped with nanosecond precision, enabling:

  • Time-travel queries
  • Full audit trails
  • Historical data analysis

Next Steps

Essential Reading

Architecture Deep-Dive

Advanced Features

Administration

Troubleshooting

Server won't start?

  • Check logs: ./bin/entitydbd.sh logs
  • Verify ports aren't in use: netstat -tlnp | grep 8085

SSL certificate errors?

  • Use -k flag for development: curl -k https://localhost:8085
  • Configure proper certificates for production

Authentication issues?

  • Verify token: curl -k -X GET https://localhost:8085/api/v1/auth/whoami -H "Authorization: Bearer $TOKEN"
  • Check user permissions in dashboard

Getting Help

Congratulations! You now have EntityDB running and understand the basics. Ready to build something amazing? 🚀