You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
_Status: Beta. [Status](server/STATUS.md) specifies which features are stable. [Breaking changes](CHANGELOG.md) are expected until 1.0._
9
+
AtomicServer is a lightweight, yet powerful CMS / Graph Database.
10
+
This repo also includes the [`atomic_lib`](lib/README.md) Rust library and [`atomic-cli`](cli/README.md).**
15
11
12
+
_Status: alpha. [Breaking changes](CHANGELOG.md) are expected until 1.0._
16
13
17
-
**Atomic-server is a graph database server for storing and sharing [Atomic Data](https://docs.atomicdata.dev/).
18
14
Demo on [atomicdata.dev](https://atomicdata.dev)**
19
15
20
-
<!--List copied from https://github.com/atomicdata-dev/atomic-data-rust/blob/master/README.md -->
16
+
<!--We re-use this table in various places, such as README.md and in the docs repo. Consider this the source.-->
21
17
- 🚀 **Fast** (less than 1ms median response time on my laptop), powered by [actix-web](https://github.com/actix/actix-web) and [sled](https://github.com/spacejam/sled)
22
18
- 🪶 **Lightweight** (8MB download, no runtime dependencies)
-[3. Run pre-compiled binary](#3-run-pre-compiled-binary)
47
+
-[4. Install using cargo](#4-install-using-cargo)
48
+
-[5. Compile from source](#5-compile-from-source)
49
+
-[Initial setup and configuration](#initial-setup-and-configuration)
50
+
-[Running using a tunneling service (easy mode)](#running-using-a-tunneling-service-easy-mode)
51
+
-[HTTPS Setup on a VPS (static IP required)](#https-setup-on-a-vps-static-ip-required)
52
+
-[HTTPS Setup using external HTTPS proxy](#https-setup-using-external-https-proxy)
53
+
-[Using `systemd` to run Atomic-Server as a service](#using-systemd-to-run-atomic-server-as-a-service)
54
+
-[Usage](#usage)
55
+
-[Using AtomicServer with the browser GUI](#using-atomicserver-with-the-browser-gui)
56
+
-[Use `atomic-cli` as client](#use-atomic-cli-as-client)
57
+
-[API](#api)
58
+
-[FAQ \& Troubleshooting](#faq--troubleshooting)
59
+
-[Can / should I create backups?](#can--should-i-create-backups)
60
+
-[I lost the key / secret to my Root Agent, and the `/setup` invite is no longer usable! What now?](#i-lost-the-key--secret-to-my-root-agent-and-the-setup-invite-is-no-longer-usable-what-now)
61
+
-[How do I migrate my data to a new domain?](#how-do-i-migrate-my-data-to-a-new-domain)
62
+
-[How do I reset my database?](#how-do-i-reset-my-database)
63
+
-[How do I make my data private, yet available online?](#how-do-i-make-my-data-private-yet-available-online)
64
+
-[Items are missing in my Collections / Search results](#items-are-missing-in-my-collections--search-results)
65
+
-[I get a `failed to retrieve` error when opening](#i-get-a-failed-to-retrieve-error-when-opening)
66
+
-[Can I embed AtomicServer in another application?](#can-i-embed-atomicserver-in-another-application)
67
+
-[Where is my data stored on my machine?](#where-is-my-data-stored-on-my-machine)
68
+
-[Also in this Repo](#also-in-this-repo)
69
+
-[`atomic-cli`](#atomic-cli)
70
+
-[`atomic-lib`](#atomic-lib)
71
+
-[Also check out](#also-check-out)
72
+
-[Contribute](#contribute)
73
+
74
+
## When should you use this
75
+
76
+
- You want a powerful, lightweight, fast and easy to use **CMS or database** with live updates, editors, modelling capabilities and an intuitive API
77
+
- You want to build a webapplication, and like working with using [React](https://github.com/atomicdata-dev/atomic-data-browser) or [Svelte](https://github.com/atomicdata-dev/atomic-svelte).
78
+
- You want to make (high-value) **datasets as easily accessible as possible**
79
+
- You want to specify and share a **common vocabulary** / ontology / schema for some specific domain or dataset. Example classes [here](https://atomicdata.dev/classes).
80
+
- You want to use and **share linked data**, but don't want to deal with most of [the complexities of RDF](https://docs.atomicdata.dev/interoperability/rdf.html), SPARQL, Triple Stores, Named Graphs and Blank Nodes.
81
+
- You are interested in **re-decentralizing the web** or want want to work with tech that improves data ownership and interoperability.
82
+
83
+
## When _not_ to use this
84
+
85
+
- High-throughput **numerical data / numerical analysis**. AtomicServer does not have aggregate queries.
86
+
- If you need **high stability**, look further (for now). This is beta sofware and can change.
87
+
- You're dealing with **very sensitive / private data**. The built-in authorization mechanisms are relatively new and not rigorously tested. The database itself is not encrypted.
88
+
-**Complex query requirements**. We have queries with filters and features for path traversal, but it may fall short. Check out NEO4j, Apache Jena or maybe TerminusDB.
89
+
90
+
## Installation & getting started
91
+
92
+
You can run AtomicServer in five ways:
93
+
94
+
1. Using docker (probably the quickest): `docker run -p 80:80 -p 443:443 -v atomic-storage:/atomic-storage joepmeneer/atomic-server`
95
+
2. Install a desktop build (macOS only as of now)
96
+
3. From a published [binary](https://github.com/atomicdata-dev/atomic-data-rust/releases)
97
+
4. Using [Cargo](https://doc.rust-lang.org/cargo/getting-started/installation.html) from crates.io: `cargo install atomic-server`
98
+
5. Manually from source
99
+
100
+
When you're running AtomicServer, go to [Initial setup and configuration](#Initial-setup-and-configuration).
101
+
If you want to run this locally as a developer / contributor, check out [the Contributors guide](CONTRIBUTE.md).
The `dockerfile` is located in the project root, above this `server` folder.
107
+
- If you want to make changes (e.g. to the port), make sure to pass the relevant CLI options (e.g. `--port 9883`).
108
+
- If you want to update, run `docker pull joepmeneer/atomic-server` and docker should fetch the latest version.
109
+
110
+
### 2. Install desktop build (macOS only)
111
+
112
+
We automatically build `.dmg` installers for MacOS. You can download them from the [releases page](https://github.com/atomicdata-dev/atomic-data-rust/releases).
113
+
114
+
### 3. Run pre-compiled binary
115
+
116
+
Get the binaries from the [releases page](https://github.com/atomicdata-dev/atomic-data-rust/releases) and copy them to your `bin` folder.
117
+
118
+
### 4. Install using cargo
119
+
120
+
```sh
121
+
# Install from source using cargo, and add it to your path
122
+
# If things go wrong, check out `Troubleshooting compiling from source:` below
- You can configure the server by passing arguments (see `atomic-server --help`), or by setting ENV variables.
148
+
- The server loads the `.env` from the current path by default. Create a `.env` file from the default template in your current directory with `atomic-server generate-dotenv`
149
+
- 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`](https://crates.io/crates/atomic-cli) and [atomic-data-browser](https://github.com/atomicdata-dev/atomic-data-browser) clients for authorization.
150
+
- A directory is made: `~/.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.
151
+
- Visit `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).
152
+
153
+
### Running using a tunneling service (easy mode)
154
+
155
+
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.
156
+
It's the easiest way to get your server to run on the web, yet still have full control over your server.
157
+
158
+
- Create an account on some tunneling service, such as [tunnelto.dev](https://tunnelto.dev/) (which we will use here). Make sure to reserve a subdomain, you want it to remain stable.
You'll probably want to make your Atomic Data available through HTTPS on some server.
165
+
You can use the embedded HTTPS / TLS setup powered by [LetsEncrypt](https://letsencrypt.org/), [acme_lib](https://docs.rs/acme-lib/0.8.1/acme_lib/index.html) and [rustls](https://github.com/ctz/rustls).
166
+
167
+
You can do this by passing these flags:
168
+
169
+
Run the server: `atomic-server --https --email some@example.com --domain example.com`.
170
+
171
+
You can also set these things using a `.env` or by setting them some other way.
172
+
173
+
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.
174
+
The default Ports are `9883` for HTTP, and `9884` for HTTPS.
175
+
If you're running the server publicly, set these to `80` and `433`: `atomic-server --https --port 80 --port-https 433`.
176
+
It will now initialize the certificate.
177
+
Read the logs, watch for errors.
178
+
179
+
HTTPS certificates are automatically renewed when the server is restarted, and the certs are 4 weeks or older.
180
+
They are stored in your `.config/atomic/` dir.
181
+
182
+
#### HTTPS Setup using external HTTPS proxy
183
+
184
+
Atomic-server has built-in HTTPS support using letsencrypt, but there are usecases for using external TLS source (e.g. Traeffik / Nginx / Ingress).
185
+
186
+
To do this, users need to set these ENVS:
187
+
188
+
```ini
189
+
ATOMIC_DOMAIN=example.com
190
+
# We'll use this regular HTTP port, not the HTTPS one
191
+
ATOMIC_PORT=80
192
+
# Disable built-in letsencrypt
193
+
ATOMIC_HTTPS=false
194
+
# Since Atomic-server is no longer aware of the existence of the external HTTPS service, we need to set the full URL here:
195
+
ATOMIC_SERVER_URL=https://example.com
196
+
```
197
+
198
+
### Using `systemd` to run Atomic-Server as a service
199
+
200
+
In Linux operating systems, you can use `systemd` to manage running processes.
201
+
You can configure it to restart automatically, and collect logs with `journalctl`.
There are three ways to interact with this server:
241
+
242
+
-**GUI**: Use the [`atomic-data-browser`](https://github.com/atomicdata-dev/atomic-data-browser) JS frontend by visiting `localhost:9883`.
243
+
-**API**: We have a subset of the [API documented using Swagger / OpenAPI](https://editor.swagger.io/?url=https://raw.githubusercontent.com/atomicdata-dev/atomic-data-rust/master/server/openapi.yml). Check out [./_requests.http](./example_requests.http) for various HTTP requests to the server. Also, [read the Atomic Data Docs](https://docs.atomicdata.dev/). You can also try the [react boilerplate](https://codesandbox.io/s/atomic-data-react-template-4y9qu?file=/src/MyResource.tsx:0-1223) to build your own front-end app using [@tomic/lib](https://www.npmjs.com/package/@tomic/lib) and [@tomic/react](https://www.npmjs.com/package/@tomic/react).
244
+
-**CLI**: The [`atomic-cli`](https://crates.io/crates/atomic-cli/0.24.2) terminal app
245
+
246
+
### Using AtomicServer with the browser GUI
247
+
248
+
Open your server in your browser.
249
+
By default, that's [`http://localhost:9883`](http://localhost:9883).
250
+
Fun fact: `⚛` is HTML entity code for the Atom icon: ⚛.
251
+
252
+
The first screen should show you your [_Drive_](https://atomicdata.dev/classes/Drive).
253
+
You can think of this as your root folder.
254
+
It is the resource hosted at the root URL, effectively being the home page of your server.
255
+
256
+
There's an instruction on the screen about the `/setup` page.
257
+
Click this, and you'll get a screen showing an [_Invite_](https://atomicdata.dev/classes/Invite).
258
+
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.
259
+
Therefore, it may be best to create an Agent on some _other_ running server, such as the [demo Invite on AtomicData.dev](https://atomicdata.dev/invites/1).
260
+
And after that, copy the Secret from the `User settings` panel from AtomicData.dev, go back to your `localhost` version, and press `sign in`.
261
+
Paste the Secret, and voila! You're signed in.
262
+
263
+
Now, again go to `/setup`. This time, you can `Accept as {user}`.
264
+
After clicking, your Agent has gotten `write` rights for the Drive!
265
+
You can verify this by hovering over the description field, clicking the edit icon, and making a few changes.
266
+
You can also press the menu button (three dots, top left) and press `Data view` to see your agent after the `write` field.
267
+
Note that you can now edit every field.
268
+
You can also fetch your data now as various formats.
269
+
270
+
Try checking out the other features in the menu bar, and check out the `collections`.
271
+
272
+
### Use `atomic-cli` as client
273
+
274
+
`atomic-cli` is a useful terminal tool for interacting with `atomic-server`.
275
+
It makes it easy to query and edit Atomic Data from the command line.
276
+
[Check it out](https://github.com/atomicdata-dev/atomic-data-rust/tree/master/cli).
277
+
278
+
### API
279
+
280
+
You can fetch individual items by sending a GET request to their URL.
281
+
282
+
```sh
283
+
# Fetch as JSON-AD (de facto standard for Atomic Data)
Check out [./example_requests.http](/example_requests.http) for more things that you can do.
294
+
We have a subset of the [API documented using Swagger / OpenAPI](https://editor.swagger.io/?url=https://raw.githubusercontent.com/atomicdata-dev/atomic-data-rust/master/server/openapi.yml).
295
+
Also, read the [Atomic Data Docs](https://docs.atomicdata.dev/) to learn more about Collections, Commits, JSON-AD and other concepts used here.
296
+
297
+
## FAQ & Troubleshooting
298
+
299
+
### Can / should I create backups?
300
+
301
+
You should. Especially before installing a newer AtomicServer version, as it might be imcompatible with the previous database model and could corrupt the database.
302
+
Run `atomic-server export` to create a backup in your `~/.config/atomic/backups` folder.
303
+
Import them using `atomic-server import -p ~/.config/atomic/backups/${date}.json`.
304
+
305
+
### I lost the key / secret to my Root Agent, and the `/setup` invite is no longer usable! What now?
306
+
307
+
You can run `atomic-server --initialize` to recreate the `/setup` invite. It will be reset to `1` usage.
308
+
309
+
### How do I migrate my data to a new domain?
310
+
311
+
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.
312
+
This could especially be helpful if you're running at `localhost:9883` and want to move to a live server.
313
+
314
+
### How do I reset my database?
315
+
316
+
Remove the `db` folder in your `atomic` config: `rm -rf ~/.config/atomic/db`.
317
+
318
+
### How do I make my data private, yet available online?
319
+
320
+
You can press the menu icon (the three dots in the navigation bar), go to sharing, and uncheck the public `read` right.
321
+
See the [Hierarchy chapter](https://docs.atomicdata.dev/hierarchy.html) in the docs on more info of the authorization model.
322
+
323
+
### Items are missing in my Collections / Search results
324
+
325
+
You might have a problem with your indexes.
326
+
Try rebuilding the indexes using `atomic-server --rebuild-index`.
327
+
Also, if you can, recreate and describe the indexing issue in the issue tracker, so we can fix it.
328
+
329
+
### I get a `failed to retrieve` error when opening
330
+
331
+
Try re-initializing atomic server `atomic-server --initialize`.
332
+
333
+
### Can I embed AtomicServer in another application?
334
+
335
+
Yes. This is what I'm doing with the Tauri desktop distribution of AtomicServer.
336
+
Check out the [`desktop`](https://github.com/atomicdata-dev/atomic-data-rust/tree/master/desktop) code for an example!
337
+
338
+
### Where is my data stored on my machine?
339
+
340
+
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`.
0 commit comments