atomic-server

AtomicServer

crates.io Discord chat MIT licensed github

Create, share, fetch and model Atomic Data! AtomicServer is a lightweight, yet powerful CMS / Graph Database. Demo on atomicdata.dev

This repo also includes:

Status: alpha. Breaking changes are expected until 1.0.

Powered by Rust, atomic-lib and more.

https://user-images.githubusercontent.com/2183313/139728539-d69b899f-6f9b-44cb-a1b7-bbab68beac0c.mp4

Table of contents

When should you use this

When not to use this

Installation & getting started

You can run AtomicServer in five ways:

  1. Using docker (probably the quickest): docker run -p 80:80 -p 443:443 -v atomic-storage:/atomic-storage joepmeneer/atomic-server
  2. Install a desktop build (macOS only as of now)
  3. From a published binary
  4. Using Cargo from crates.io: cargo install atomic-server
  5. Manually from source

When you’re running AtomicServer, go to Initial setup and configuration. If you want to run this locally as a developer / contributor, check out the Contributors guide.

1. Run using docker

2. Install desktop build (macOS only)

We automatically build .dmg installers for MacOS. You can download them from the releases page.

3. Run pre-compiled binary

Get the binaries from the releases page and copy them to your bin folder.

4. Install using cargo

# Make sure pnpm is installed and available in path! https://pnpm.io/
pnpm --version
# Install from source using cargo, and add it to your path
# If things go wrong, check out `Troubleshooting compiling from source:` below
cargo install atomic-server --locked
# Check the available options and commands
atomic-server --help
# Run it!
atomic-server

5. Compile from source

# make sure pnpm is installed and available in path! https://pnpm.io/
pnpm --version
git clone git@github.com:atomicdata-dev/atomic-server.git
cd atomic-server/server
cargo run

If things go wrong while compiling from source:

# If cc-linker, pkg-config or libssl-dev is not installed, make sure to install them
sudo apt-get install -y build-essential pkg-config libssl-dev --fix-missing

Initial setup and configuration

Running using a tunneling service (easy mode)

If you want to make your -server available on the web, but don’t want (or cannot) deal with setting up port-forwarding and DNS, you can use a tunneling service. It’s the easiest way to get your server to run on the web, yet still have full control over your server.

HTTPS Setup on a VPS (static IP required)

You’ll probably want to make your Atomic Data available through HTTPS on some server. You can use the embedded HTTPS / TLS setup powered by LetsEncrypt, acme_lib and rustls.

You can do this by passing these flags:

Run the server: atomic-server --https --email some@example.com --domain example.com.

You can also set these things using a .env or by setting them some other way.

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. The default Ports are 9883 for HTTP, and 9884 for HTTPS. If you’re running the server publicly, set these to 80 and 433: atomic-server --https --port 80 --port-https 433. 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. They are stored in your .config/atomic/ dir.

HTTPS Setup using external HTTPS proxy

Atomic-server has built-in HTTPS support using letsencrypt, but there are usecases for using external TLS source (e.g. Traeffik / Nginx / Ingress).

To do this, users need to set these ENVS:

ATOMIC_DOMAIN=example.com
# We'll use this regular HTTP port, not the HTTPS one
ATOMIC_PORT=80
# Disable built-in letsencrypt
ATOMIC_HTTPS=false
# Since Atomic-server is no longer aware of the existence of the external HTTPS service, we need to set the full URL here:
ATOMIC_SERVER_URL=https://example.com

Using systemd to run Atomic-Server as a service

In Linux operating systems, you can use systemd to manage running processes. You can configure it to restart automatically, and collect logs with journalctl.

Create a service:

nano /etc/systemd/system/atomic.service

Add this to its contents, make changes if needed:

[Unit]
Description=Atomic-Server
#After=network.targetdd
StartLimitIntervalSec=0[Service]

[Service]
Type=simple
Restart=always
RestartSec=1
User=root
ExecStart=/root/atomic-server
WorkingDirectory=/root/
EnvironmentFil=/root/.env

[Install]
WantedBy=multi-user.target

# start / status / restart commands:
systemctl start atomic
systemctl status atomic
systemctl restart atomic
# show recent logs, follow them on screen
journalctl -u atomic.service --since "1 hour ago" -f

Usage

There are three ways to interact with this server:

Using AtomicServer with the browser GUI

Open your server in your browser. By default, that’s http://localhost:9883. Fun fact: ⚛ is HTML entity code for the Atom icon: ⚛.

The first screen should show you your Drive. You can think of this as your root folder. It is the resource hosted at the root URL, effectively being the home page of your server.

There’s an instruction on the screen about the /setup page. Click this, and you’ll get a screen showing an Invite. Normally, you could Accept as new user, but since you’re running on localhost, you won’t be able to use the newly created Agent on non-local Atomic-Servers. Therefore, it may be best to create an Agent on some other running server, such as the demo Invite on AtomicData.dev. And after that, copy the Secret from the User settings panel from AtomicData.dev, go back to your localhost version, and press sign in. Paste the Secret, and voila! You’re signed in.

Now, again go to /setup. This time, you can Accept as {user}. After clicking, your Agent has gotten write rights for the Drive! You can verify this by hovering over the description field, clicking the edit icon, and making a few changes. You can also press the menu button (three dots, top left) and press Data view to see your agent after the write field. Note that you can now edit every field. You can also fetch your data now as various formats.

Try checking out the other features in the menu bar, and check out the collections.

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. We have a subset of the API documented using Swagger / OpenAPI. Also, read the Atomic Data Docs to learn more about Collections, Commits, JSON-AD and other concepts used here.

FAQ & Troubleshooting

How do I make a website using this CMS?

Check out atomic-sveltekit-demo

Can / should I create backups?

You should. Run atomic-server export to create a JSON-AD backup in your ~/.config/atomic/backups folder. Import them using atomic-server import -p ~/.config/atomic/backups/${date}.json.’ You could also copy all folders atomic-server uses. To see what these are, see atomic-server show-config.

I lost the key / secret to my Root Agent, and the /setup invite is no longer usable! What now?

You can run atomic-server --initialize to recreate the /setup invite. It will be reset to 1 usage.

How do I migrate my data to a new domain?

There are no helper functions for this, but you could atomic-server export your JSON-AD, and find + replace your old domain with the new one. This could especially be helpful if you’re running at localhost:9883 and want to move to a live server.

How do I reset my database?

atomic-server reset

How do I make my data private, yet available online?

You can press the menu icon (the three dots in the navigation bar), go to sharing, and uncheck the public read right. See the Hierarchy chapter in the docs on more info of the authorization model.

Items are missing in my Collections / Search results

You might have a problem with your indexes. Try rebuilding the indexes using atomic-server --rebuild-index. Also, if you can, recreate and describe the indexing issue in the issue tracker, so we can fix it.

I get a failed to retrieve error when opening

Try re-initializing atomic server atomic-server --initialize.

Can I embed AtomicServer in another application?

Yes. This is what I’m doing with the Tauri desktop distribution of AtomicServer. Check out the desktop code for an example!

I want to use my own authorization. How do I do that?

You can disable all authorization using --public-mode. Make sure AtomicServer is not publicly accessible, because this will allow anyone to read any data.

Where is my data stored on my machine?

It depends on your operating system, because some data is temporary, others are configuration files, and so forth. Run atomic-server show-config to see the used paths. You can overwrite these if you want, see --help.

https://user-images.githubusercontent.com/2183313/139728539-d69b899f-6f9b-44cb-a1b7-bbab68beac0c.mp4

Also in this Repo

atomic-cli

crates.io

A simple Command Line Interface tool to fetch, create and query Atomic Data. Especially useful for interacting with an AtomicServer.

→ Read more

atomic-lib

crates.io Released API docs

A Rust library to serialize, parse, store, convert, validate, edit, fetch and store Atomic Data. Powers both atomic-cli and atomic-server.

→ Read more

Atomic Data Browser

Front-end for Atomic-Server, built with React.

@tomic/lib

Library with Store, Commit, JSON-AD parsing, and more.

docs

@tomic/react

React library with many useful hooks for rendering and editing Atomic Data.

docs

Also check out

Contribute

Issues and PR’s are welcome! And join our Discord! Read more in the Contributors guide.

This site is open source. Improve this page.