Site.js

Site.js ❤️ Owncast

Site.js is now the easiest way to set up and run your own Owncast instance.

On your production server, run:

site enable --owncast

That’s it!

This will install Owncast, set it up as a systemd service, and serve it securely at your hostname.

As usual, your Let’s Encrypt certificates will be automatically provisioned when you first hit your server and get renewed automatically for you from there on.

Note that while Site.js will get automatic updates, Owncast will not. However, newer versions of Site.js will always include the latest Owncast install script. Currently, to update Owncast, simply disable your server using site disable and re-enable it using the command above.

The Small Web is for people (not startups, enterprises, or governments).

One person.
Develop and test on your own device.
One server.
Sync and deploy to your own VPS.
One site.
Host your own site at your own domain.

Develop, test, sync, and deploy (using a single tool that comes in a single binary).

Just works.
No configuration; get started in seconds on Linux, macOS, and Windows.
Free as in freedom.
And small as in small tech.
Secure by default.
Automatic TLS everywhere with Let’s Encrypt and mkcert.
For static sites.
Write plain HTML, CSS, JS or use the bundled Hugo static site generator.
For dynamic sites.
Use simple DotJS or the full power of Node.js and Express.js.
And more…
WebSockets, database, proxy, live reload, sync, auto-update, statistics, etc.

Get started in seconds

Install Site.js.
Launch a terminal window (on Windows, a PowerShell session running under Windows Terminal) and follow along.
Tip
The following command pipes the installation script into your shell. Make sure you understand what any script does before piping it into your shell.
This installation script downloads the correct Site.js binary for your platform and places it on your path. View the source of the Linux and macOS and Windows scripts.
You can click/tap the code samples to copy them to the clipboard.
Linux
```
wget -qO- https://sitejs.org/install | bash
```
macOS
```
curl -s https://sitejs.org/install | bash
```
Windows
```
iex(iwr -UseBasicParsing https://sitejs.org/install.txt).Content
```
Create a basic static web page.
1. Create a folder.
```
mkdir hello-world
```
2. Enter the folder.
```
cd hello-world
```
3. Write the string 'Hello, world' into a file called index.html, creating or overwriting it as necessary.
  Linux and macOS
```
echo 'Hello, world' > index.html
```
  Windows
```
echo 'Hello, world' | Out-File -Encoding UTF8 index.html
```
Start the server.
```
site
```
Site.js starts serving your hello-world site at https://localhost. Go there in your browser to see your “Hello, world!” message.
Congratulations, you’re up and running with Site.js!
Tip
Do the same thing on a VPS server and start the server using site enable and you’ll have a secure production web daemon that survives errors/reboots and auto-updates itself.

Static sites with Hugo

The type of site you just created is an old-school static site. You can create static sites with Site.js using plain old HTML, CSS, and JavaScript. Site.js will automatically serve any files it finds in the folder you start it on as static files.

For larger sites, hand-rolling your static site might become cumbersome. That’s why Site.js comes bundled with the Hugo static site generator.

Let’s create a new Hugo site and start serving it.

Set up a new project.
1. Create a folder.
```
mkdir my-hugo-site
```
2. Enter the folder.
```
cd my-hugo-site
```
Create a new Hugo site.
```
site hugo new site .hugo
```
Tip
You can pass any command you would normally pass to Hugo using Site.js’s integrated Hugo instance: site hugo <any valid Hugo command>. So the above command is equivalent to running hugo new site .hugo if you have Hugo installed separately.)

Create a basic page layout.

Linux and macOS

echo '<body><h1>Hello, world!</h1></body>' > .hugo/layouts/index.html

Windows

echo '<body><h1>Hello, world!</h1></body>' | Out-File -Encoding UTF8 .hugo/layouts/index.html

Start the server.
```
site
```
Site.js starts serving your Hugo site at https://localhost. Go there in your browser to see your “Hello, world!” message.
Congratulations, you just created your first Hugo site with Site.js!
Tip
If Site.js finds a folder called .hugo in your site’s root, it will build it using its integrated Hugo instance (you don’t need to install Hugo separately) and place the generated files into a folder called .generated in your site’s root. It will also automatically serve these files.
If you alter the file you created in this example, Site.js will automatically rebuild it using Hugo and your browser will reflect the changes immediately using live reload.
See the Site.js Hugo documentation and the official Hugo documentation for detailed information on how Hugo works and how it’s integrated into Site.js.

Dynamic sites with DotJS

Site.js does not limit you to creating and serving fully static sites. You can easily add dynamic functionality to your static sites or create fully dynamic sites.

The easiest way to get started with dynamic sites is to use DotJS. DotJS gives you PHP-like simplicity in JavaScript using simple .js files.

Follow along to create a very basic dynamic site that updates a counter every time the home page is reloaded.

Create the project structure.
1. Create the folders.
  Make a project folder called count and a special nested folder in that called .dynamic:
```
mkdir -p count/.dynamic
```
2. Enter the dynamic routes folder.
```
cd count/.dynamic
```
Tip
.dynamic is a special folder in that Site.js knows to look for it in your project. If it finds it, it knows to run its contents as a dynamic route instead of serving it as static content.
Create a dynamic route.
Make a file called index.js that holds the dynamic counter route:
Linux and macOS
```
echo 'i=0; module.exports=(_, res) => res.html(`${++i}`)' > index.js
```
Windows
```
echo 'i=0; module.exports=(_, res) => res.html(`${++i}`)' | Out-File -Encoding UTF8 index.js
```
Tip
If the code here looks cryptic to you, see the longer version.
Serve your site.
```
site ..
```
Tip
You don’t have to be in the folder you want Site.js to serve, as in the previous examples. As shown here, you can specify the folder as an argument to the site command. In this case, we want to serve the whole site from the parent folder, not just the .dynamic folder.)
Hit https://localhost and refresh to see the counter update.
Congratulations, you just made your first fully dynamic DotJS site!
Tip
If you found the code in the dynamic route we created hard to read, you’re not alone. It was purposefully written to keep the example short enough to enter into terminal.
Here’s a slightly more verbose version of index.js that’s easier to understand that you might want to enter using your favourite code editor:
```
let counter = 0

module.exports = (request, response) => {
  response.html(`<h1>Hit count: ${++counter}</h1>`)
}
```
If this reminds you of a route in Express, that’s because that’s exactly what it is.
The only difference is that you don’t have to write any other code or worry about anything else including installing Node.js, provisioning TLS certificates, ensuring your site automatically restarts on reboots, etc.
(You might not recognise the .html() method on the response object as that’s a Site.js addition to make your life easier. It corresponds to writing .type('html').end() in Express.)
You can also define named parameters for your DotJS routes and Site.js does not limit you to using DotJS, either.
If you want to, you can use the full power of Express and Node.js with advanced routing. And, since it is just Node.js under the hood, you can do anything you can with Node.js including using node modules, etc.
See the Site.js documentation for more information on building dynamic sites.

WebSockets

In addition to static routes and dynamic HTTPS routes, you can also specify secure WebSocket (WSS) routes in DotJS. And you can mix all three types of routes as you please.

To see WebSockets in action, let’s create a very simple chat app.

Create the project structure.
```
mkdir -p chat/.dynamic/.wss
```

Create the chat server.

Linux and macOS

echo '
  module.exports = function (client, request) {
    // Set the room based on the route’s URL.
    client.room = this.setRoom(request)

    // Create a message handler.
    client.on("message", message => {
      // Broadcast a received message to everyone in the room.
      this.broadcast(client, message)
    })
  }
' > chat/.dynamic/.wss/chat.js

Windows

echo '
  module.exports = function (client, request) {
    // Set the room based on the route URL.
    client.room = this.setRoom(request)

    // Create a message handler.
    client.on("message", message => {
      // Broadcast a received message to everyone in the room.
      this.broadcast(client, message)
    })
  }
' | Out-File -Encoding UTF8 chat/.dynamic/.wss/chat.js

Create the chat client.

Linux and macOS

echo '
  <!doctype html>
  <html lang="en">
  <title>Chat</title>
  <h1>Chat</h1>
  <form name="messageForm">
    <input name="message" type="text">
    <button>Send</button>
  </form>
  <h2>Messages</h2>
  <ul id="messageList"></ul>
  <script>
    const socket = new WebSocket(`wss://${window.location.hostname}/chat`)

    const showMessage = message => {
      const list = document.querySelector("#messageList")
      list.innerHTML += `<li>${message.text}</li>`
    }

    socket.onmessage = message => {
      showMessage(JSON.parse(message.data))
    }

    document.messageForm.addEventListener("submit", event => {
      const message ={ text: event.target.message.value }
      socket.send(JSON.stringify(message))
      showMessage(message)
      event.preventDefault()
    })
  </script>
' > chat/index.html

Windows

echo '
<!doctype html>
<html lang="en">
<title>Chat</title>
<h1>Chat</h1>
<form name="messageForm">
  <input name="message" type="text">
  <button>Send</button>
</form>
<h2>Messages</h2>
<ul id="messageList"></ul>
<script>
  const socket = new WebSocket(`wss://${window.location.hostname}/chat`)

  const showMessage = message => {
    const list = document.querySelector("#messageList")
    list.innerHTML += `<li>${message.text}</li>`
  }

  socket.onmessage = message => {
    showMessage(JSON.parse(message.data))
  }

  document.messageForm.addEventListener("submit", event => {
    const message ={ text: event.target.message.value }
    socket.send(JSON.stringify(message))
    showMessage(message)
    event.preventDefault()
  })
</script>
'| Out-File -Encoding UTF8 chat/index.html

Launch the server.
```
site chat
```
Start the server.
To test your chat app, open up two or more web browser windows at https://localhost and play with the chat interface.
Tip
The broadcast method, by default, has rudimentary client filtering and only sends a message to clients other than the one that originally sent the message and only to clients connected to the same route (or “room”).
For a fully-documented version of the above example, see the source code for the Simple Chat example.
To run that example, first clone the Site.js source code repository:
```
git clone https://github.com/small-tech/site.js
```
Then run the simple chat example using Site.js:
```
site site.js/examples/simple-chat
```
Finally, open https://localhost in multiple browser windows and play with the chat interface.
The WebSocket functionality is from our fork of express-ws (which in turn uses ws). Both of those links have more usage details.
For full details, see the Dynamic Sites documentation and view the examples.

Database

Site.js also has a fast and simple JavaScript Database (JSDB) built into it. You can refer to the database for your app any of your routes using the global db instance.

Let’s see how easy it is to use JSDB by persisting the messages our simple chat app.

Update the server.

The code you need to add is presented in boldface.

module.exports = function (client, request) {
  // Ensure the messages table exists.
  if (!db.messages) {
    db.messages = []
  }

  // Set the room based on the route’s URL.
  client.room = this.setRoom(request)

  // Send new clients all existing messages.
  client.send(JSON.stringify(db.messages))

  // Create a message handler.
  client.on('message', message => {
    // Parse the message JSON string into a JavaScript object.
    const parsedMessage = JSON.parse(message)

    // Persist the message.
    db.messages.push(parsedMessage)

    // Broadcast a received message to everyone in the room.
    this.broadcast(client, message)
  })
}

Update the client.

You need to update the client so that it can handle the initial list of messages that is sent when someone joins the chat.

Again, the code you need to add is presented in boldface.

<!doctype html>
<html lang="en">
<title>Chat</title>
<h1>Chat</h1>
<form name="messageForm">
  <input name="message" type="text">
  <button>Send</button>
</form>
<h2>Messages</h2>
<ul id="messageList"></ul>
<script>
  const socket = new WebSocket(`wss://${window.location.hostname}/chat`)

  const showMessage = message => {
    const list = document.querySelector("#messageList")
    list.innerHTML += `<li>${message.text}</li>`
  }

  socket.onmessage = websocketMessage => {
    // Deserialise the data.
    const data = JSON.parse(websocketMessage.data)

    if (Array.isArray(data)) {
      // Display initial list of messages we get when we join a room.
      data.forEach(message => showMessage(message))
    } else {
      // Display a single message.
      showMessage(data)
    }
  }

  document.messageForm.addEventListener("submit", event => {
    const message = { text: event.target.message.value }
    socket.send(JSON.stringify(message))
    showMessage(message)
    event.preventDefault()
  })
</script>

Tip

This barely scratches the surface of what JSDB is and what you can do with it.

JSDB is an in-memory JavaScript database that persists tables to append-only transaction logs in JavaScript Data Format (JSDF) which is a subset of JavaScript.

It also has its own query language called JavaScript Query Language (JSQL). So, for example, if you wanted to get a list of messages that contained the hashtag #BLM, you could do so like this:

db.messages.where('text').includesCaseInsensitive('#blm').get()

Find out more about JSDB in this introductory blog post, in the Site.js JSDB documentation, and in the JSDB documentation. See the source code for the persisted chat example for a more comprehensive version of the sample presented here.

Proxy servers

You can use Site.js as a proxy to add automatic TLS for HTTP and WebSocket to any web app.

Create a simple insecure service

ForThe following is a simple HTTP server written in Python 3 (server.py) that runs insecurely on port 3000:

from http.server import HTTPServer, BaseHTTPRequestHandler
class MyRequestHandler(BaseHTTPRequestHandler):
  def do_GET(self):
    self.send_response(200)
    self.end_headers()
    self.wfile.write(b'Hello, from Python!')

server = HTTPServer(('localhost', 3000), MyRequestHandler)
server.serve_forever()

Run it
To keep things simple, the following command will simply run it in the background.
```
$ python3 server &
```
Serve it securely using Site.js
```
$ site enable :3000
```

Like this? Fund us!

Made with love by Small Technology Foundation.

We are a tiny not-for-profit based in Ireland that makes tools for people like you – not for startups, enterprises, or governments. And we’re also funded by people like you. If you like our work and want to help us continue to exist, please fund us.

Site.js is Small Technology.

The Small Web is for people (not startups, enterprises, or governments).

One person.

One server.

One site.

Develop, test, sync, and deploy (using a single tool that comes in a single binary).

Just works.

Free as in freedom.

Secure by default.

For static sites.

For dynamic sites.

And more…

Get started in seconds

Install Site.js.

Linux

macOS

Windows

Create a basic static web page.

Linux and macOS

Windows

Start the server.

Static sites with Hugo

Set up a new project.

Create a new Hugo site.

Create a basic page layout.

Linux and macOS

Windows

Start the server.

Dynamic sites with DotJS

Create the project structure.

Create a dynamic route.

Linux and macOS

Windows

Serve your site.

WebSockets

Create the project structure.

Create the chat server.

Linux and macOS

Windows

Create the chat client.

Linux and macOS

Windows

Launch the server.

Database

Update the server.

Update the client.

Proxy servers

Create a simple insecure service

Run it

Serve it securely using Site.js

Further reading

Multi-device testing

Sync

Evergreen Web

Custom error pages

Ephemeral statistics

Documentation

Like this? Fund us!