`atomic-server`

Status: Alpha. Not ready for production time. Prone to changes and corrupt databases when upgrading. Changelog

The easiest way to share Atomic Data on the web. atomic-server is a web-first database for storing and sharing typed linked data. Demo on atomicdata.dev

No runtime dependencies, fast, runs on all platforms
Embedded HTTP / HTTPS / HTTP2.0 server
Serialization to HTML, JSON, Linked Data (RDF/XML, N-Triples / Turtle / JSON-LD) and JSON-AD
Uses atomic-data-abrowser as front-end.

When should you use this

You want to make (high-value) datasets as easily accessible as possible
You can afford to create or find an Atomic Schema for your dataset (use atomic-cli new class for this). Example classes here.
You want to use and share linked data, but don't want to deal with most of the complexities of RDF, SPARQL, Triple Stores, Named Graphs and Blank Nodes.
You like living on the edge (this application is not production ready)

SUBCOMMANDS:
    export    Create a JSON-AD backup of the store.
    import    Import a JSON-AD backup to the store. Overwrites Resources with same @id.
    run       Starts the server

Installation & getting started

You can run atomic-server in four ways:

Install using Cargo: cargo install atomic-server
Using docker
From a published binary
From source

Run using docker

The dockerfile is located in the project root, above this server folder.

Run: docker run -p 80:80 -p 443:443 -v atomic-storage:/atomic-storage joepmeneer/atomic-server
If you want to update, run docker pull joepmeneer/atomic-server and docker should fetch the latest version.

Install from source

# Clone this repoo
git clone git@github.com:joepio/atomic.git
cd atomic/server
# Optional, but recommended: Create a new .env using the template.
cp default.env .env
# Run the server. It creates a store in ~/.config/atomic/db by default
cargo run
# Or tun the extra-cool desktop version with a presence in your app tray
cargo run --features desktop
# Visit http://localhost

Initial setup and configuration

The server loads the .env from the current path by default. Use the default.env from this repo as a template and for reference.
If you want to run Atomic Server on your own domain, you'll probably want to set ATOMIC_DOMAIN, ATOMIC_HTTPS and ATOMIC_EMAIL (see HTTPS setup below)
After running the server, check the logs and take note of the Agent Subject and Private key. You should use these in the atomic-cli and atomic-data-browser clients for authorization.
A directory is made: ~/.config/atomic, which stores your newly created Agent keys, your data, the HTTPS certificates and a folder for public static files.

HTTPS Setup

You'll probably want to make your Atomic Data available through HTTPS. You can use the embedded HTTPS / TLS setup powered by LetsEncrypt, acme_lib and rustls. To setup HTTPS, we'll need to set some environment variables. Open .env and set:

ATOMIC_EMAIL=youremail@example.com
ATOMIC_DOMAIN=example.com
ATOMIC_HTTPS=true

Run the server: cargo run. Make sure the server is accessible at ATOMIC_DOMAIN at port 80, because Let's Encrypt will send an HTTP request to this server's /.well-known directory to check the keys. It will now initialize the certificate. Read the logs, watch for errors.

HTTPS certificates are automatically renewed when the server is restarted, and the certs are 4 weeks or older.

Usage

There are three ways to interact with this server:

GUI: Use the atomic-data-browser JS frontend by visiting localhost.
API: Check out ./example_requests.http for various HTTP requests to the server. Also, read the docs!
CLI: The atomic-cli terminal app

Use `atomic-cli` as client

atomic-cli is a useful terminal tool for interacting with atomic-server. It makes it easy to query and edit Atomic Data from the command line. Check it out.

API

You can fetch individual items by sending a GET request to their URL.

# Fetch as JSON-AD (de facto standard for Atomic Data)
curl -i -H "Accept: application/ad+json" https://atomicdata.dev/properties/shortname
# Fetch as JSON-LD
curl -i -H "Accept: application/ld+json" https://atomicdata.dev/properties/shortname
# Fetch as JSON
curl -i -H "Accept: application/json" https://atomicdata.dev/properties/shortname
# Fetch as Turtle / N3
curl -i -H "Accept: text/turtle" https://atomicdata.dev/properties/shortname

Check out ./example_requests.http for more things that you can do.

Extra commands

The atomic-server binary has some extra CLI commands: import and export. Run atomic-server --help to read more.

Testing

# This also makes sure that cli and server work, plus it test the db feature
cargo test --all

Performance benchmarking

# Install drill
cargo install drill
drill -b benchmark.yml --stats

atomic-server 0.23.4

atomic-server