|
Important
|
This is the repository for Site 1.0. If you are looking for the latest version (Site 2.0), it is at https://github.com/juxt-site/site. |
Site supports web content, and OpenAPI. You can use Site as a versioned Content Management System.
An official (work in progress) documentation website can be found here.
|
Note
|
A new version of Site is being developed here: https://github.com/juxt-site/site |
Site is a Resource Server, built on the XTDB database.
You can put things into Site with (HTTP) PUT requests. When you do this, Site will put (the representation of) your thing (document, image, video, data…) into the database. You can get these later with a (HTTP) GET request with the same URI. In this way, Site behaves like a web server, with an immutable bitemporal content store.
If you PUT a JSON document with a Content-Type of
application/vnd.oai.openapi+json;version=3.0.2, Site will treat this as an
OpenAPI API definition, and serve that API for
you. This OpenAPI API definition will contain the API endpoints, and provide
schemas for the data transferred by the API. This tells the server how to
validate data coming in to the API, and how to construct data on the way out.
APIs served from Site are good web citizens. They implement HTTP method semantics properly, with support for content negotiation, conditional requests, range requests and authentication.
APIs are also able to benefit from Site’s authorization module, Pass, providing Policy-Based Access Control, loosely based on XACML.
Before you start, you’ll need to have the following installed:
$ git clone https://github.com/juxt/site
It is recommended to install openssl and openjdk and make sure JAVA_HOME
is set correctly. At the time of writing brew installs openjdk 17.02 and openssl
3.0.1:
$ brew install openssl $ echo export JAVA_HOME=/usr/local/Cellar/openjdk/17.0.2/libexec/openjdk.jdk/Contents/Home >> ~/.zshrc $ exec zsh -l
Check that Java can find libcrypto:
$ cd site # (if needed) $ clojure -A:dev -M:test -m kaocha.runner --focus juxt.site.authz-test
The test should run just fine. If instead $JAVA_HOME/bin/java aborts (signal 6) with the message:
$ ...
$ ... WARNING: ${JAVA_HOME}/bin/java is loading libcrypto in an unsafe way
you need to make libcrypto visible to $JAVA_HOME/bin/java by running e.g.:
$ ln -s /usr/local/Cellar/openssl@3/3.0.1/lib/libcrypto.dylib $JAVA_HOME/lib
There’s a sample configuration in etc you should copy to $HOME/.config/site/config.edn.
$ mkdir -p $HOME/.config/site $ cp site/etc/config.edn $HOME/.config/site/config.edn
|
Tip
|
If you have $ pass generate -n site/local/admin |
Start the Site server:
$ site/bin/site-server
|
Note
|
Alternatively, if you’re familiar with Clojure development, you can start
the server via the deps.edn file and simply 'jack-in' with your editor or IDE
as normal.
|
If you require multiple Site servers to coexist on the same machine, you can start site passing a different configuration file as follows:
$ SITE_CONFIG=/absolute/path/custom-site-config.edn site/bin/site-server
In this case please be sure to change the configuration so ports are different and XTDB files are stored in a separate folder than the ones specified in the example configuration file. You’ll also need to specify Site host:port when using site commands, for example:
$ SITE_BASE_URI=http://localhost:5509 site/bin/site get-token -u admin
Optionally, you can also get Site up and running using the provided Docker image. You need Docker installed in your system, then execute the following from the command line (sudo might not be necessary depending on your installation):
sudo docker build -t juxt/site:latest .
sudo docker run -p 2021:2021 -p 50505:50505 -d juxt/site:latestIf you’ve run Site via your development environment and 'jacked-in' you’ll already have a REPL. Proceed to the next step.
If you’re running Site with site/bin/site-server, you’ll need to connect a
terminal to Site to access the REPL. You can do this via port 50505, which is a
socket REPL that Site starts by default.
How you connect to this port is up to you. One way is via ncat, but you can replace ncat with telnet, or netcat, depending on what’s available for your system.
|
Note
|
Arch users can install $ sudo pacman -Sy nmap |
$ ncat localhost 50505
|
Tip
|
Prefix the command with $ rlwrap ncat localhost 50505 |
Bootstrap the new system by adding the minimum resources that are required to allow remote access.
Site by JUXT. Copyright (c) 2021, JUXT LTD.
Type :repl/quit to exit
[ ] Site API not installed. Enter (put-site-api!) to fix this.
[ ] Authentication resources not installed. Enter (put-auth-resources!) to fix this.
[ ] Role of superuser not yet created. Enter (put-superuser-role!) to fix this.
[ ] No superusers exist. Enter (put-superuser! <username> <fullname>)
or (put-superuser! <username> <fullname> <password>) to fix this.
site>
Install the Site API:
site> (put-site-api!)
Install the authentication rules:
site> (put-auth-resources!)
Install the superuser role:
site> (put-superuser-role!)
Finally, create a superuser. If you have pass installed, this will fetch the password directly:
site> (put-superuser! "admin" "Administrator")
|
Note
|
We recommend that you generate a password with pass.
|
If you don’t have pass installed, you can add a password as a final argument to put-superuser!.
site> (put-superuser! "admin" "Administrator" "admin")
Replace "admin", "Administrator" and "admin" with your own username, full name and password respectively.
Quit the REPL, for example, with Ctrl-C or by typing :repl/quit.
The site tool is a command-line utility that allows you to remotely administer site.
If you’re on MacOS, you will need to install the gnu version of readlink. You can do so with brew:
brew install coreutils
ln -s /usr/local/bin/greadlink /usr/local/bin/readlinkWe must first get a token that we can use for API access. This process authenticates to the site server using your password.
admin with your username (or let it default to your OS username)$ site/bin/site get-token -u admin
Now we can use the site tool for remote administration. Try the following:
$ site/bin/site list-users
By default, tokens last for an hour. That can sometimes mean they expire during work sessions. You can set the expiry time of new tokens via the REPL.
(put! (assoc (e "http://localhost:2021/_site/token") ::pass/expires-in (* 24 3600)))
The MIT License (MIT)
Copyright © 2020-2021 JUXT LTD.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.