joepmeneer/atomic-server
Headless CMS / Open Source Notion alternative
10K+
atomic-server
Status: Beta. Breaking changes are expected until 1.0.
Atomic-server is a graph database server for storing and sharing Atomic Data. Demo on atomicdata.dev
Powered by Rust, atomic-lib and more.
/setup
invite is no longer usable! What now?failed to retrieve
error when openingrdf-search
mode?You can run atomic-server
in four ways:
cargo install atomic-server
When you're running atomic-server
, go to Initial setup and configuration.
If you want to run this locally as a developer / contributor, check out the Contributors guide.
# 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
The dockerfile
is located in the project root, above this server
folder.
docker run -p 80:80 -p 443:443 -v atomic-storage:/atomic-storage joepmeneer/atomic-server
--port 9883
).docker pull joepmeneer/atomic-server
and docker should fetch the latest version.git clone git@github.com:joepio/atomic-data-rust.git
cd atomic-data-rust/server
cargo run
# 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
atomic-server --help
), or by setting ENV variables..env
from the current path by default. Create a .env
file from the default template in your current directory with atomic-server setup-env
.Agent Subject
and Private key
. You should use these in the atomic-cli
and atomic-data-browser clients for authorization.~/.config/atomic
, which stores your newly created Agent keys, the HTTPS certificates other configuration. Depending on your OS, the actual data is stored in different locations. See use the show-config
command to find out where, if you need the files.http://localhost:9883/setup
to register your first (admin) user. You can use an existing Agent, or create a new one. Note that if you create a localhost
agent, it cannot be used on the web (since, well, it's local).If you want to make your atomic-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.
tunnelto --port 9883 --subdomain joepio --key YOUR_API_KEY
atomic-server --domain joepio.tunnelto.dev --custom-server-url 'https://joepio.tunnelto.dev' --initialize
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.
There are three ways to interact with this server:
atomic-data-browser
JS frontend by visiting localhost:9883
.atomic-cli
terminal appOpen 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
.
atomic-cli
as clientatomic-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.
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.
You should. Especially before installing a newer Atomic-Server version, as it might be imcompatible with the previous database model and could corrupt the database.
Run atomic-server export
to create a backup in your ~/.config/atomic/backups
folder.
Import them using atomic-server import -p ~/.config/atomic/backups/${date}.json
.
/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.
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.
Remove the db
folder in your atomic
config: rm -rf ~/.config/atomic/db
.
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.
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.
failed to retrieve
error when openingTry re-initializing atomic server atomic-server --initialize
.
rdf-search
mode?This turns atomic-server
into a full-text search server that indexed RDF Turtle documents.
Check out the readme.
Yes. This is what I'm doing with the Tauri desktop distribution of Atomic-Server.
Check out the desktop
code for an example!
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
.
docker pull joepmeneer/atomic-server