WIP manual work
This commit is contained in:
Zef Hemel
@@ -1,23 +1,12 @@
|
||||
SilverBullet is primarily configured via environment variables. This page gives a comprehensive overview of all configuration options. You can set these ad-hoc when running the SilverBullet server, or e.g. in your [[Install/Local$docker|docker-compose file]].
|
||||
SilverBullet is primarily configured via environment variables. This page gives a comprehensive overview of all configuration options. You can set these ad-hoc when running the SilverBullet server, or e.g. in your [[Install/Docker|docker-compose file]].
|
||||
|
||||
# Network
|
||||
$network
|
||||
Note: these options are primarily useful for [[Install/Deno]] deployments, not so much for [[Install/Docker]].
|
||||
|
||||
* `SB_HOSTNAME`: Set to the hostname to bind to (defaults to `127.0.0.0`, set to `0.0.0.0` to accept outside connections for the local deno setup, defaults to `0.0.0.0` for docker)
|
||||
* `SB_PORT`: Sets the port to listen to, e.g. `SB_PORT=1234`, default is `3000`
|
||||
|
||||
# Run mode
|
||||
$runmode
|
||||
|
||||
* `SB_SYNC_ONLY`: If you want to run SilverBullet in a mode where the server purely functions as a simple file store and doesn’t index or process content on the server, you can do so by setting this environment variable to `true`. As a result, the client will always run in the Sync [[Client Modes|client mode]].
|
||||
|
||||
# Security
|
||||
$security
|
||||
|
||||
SilverBullet enables plugs to run shell commands. This is used by e.g. the [[🔌 Git]] plug to perform git commands. This is potentially unsafe. If you don’t need this, you can disable this functionality:
|
||||
|
||||
* `SB_SHELL_BACKEND`: Enable/disable running of shell commands from plugs, defaults to `local` (enabled), set to `off` to disable. It is only enabled when using a local folder for [[$storage]].
|
||||
|
||||
# Authentication
|
||||
$authentication
|
||||
SilverBullet supports basic authentication for a single user.
|
||||
@@ -27,7 +16,7 @@ SilverBullet supports basic authentication for a single user.
|
||||
|
||||
# Storage
|
||||
$storage
|
||||
SilverBullet supports multiple storage backends for keeping your [[Space]] content.
|
||||
SilverBullet supports multiple storage backends for keeping your [[Spaces]] content.
|
||||
|
||||
## Disk storage
|
||||
This is the default and simplest backend to use: a folder on disk. It is configured as follows:
|
||||
@@ -90,6 +79,19 @@ The in-memory database is only useful for testing.
|
||||
|
||||
* `SB_DB_BACKEND`: `memory`
|
||||
|
||||
# Run mode
|
||||
$runmode
|
||||
|
||||
* `SB_SYNC_ONLY`: If you want to run SilverBullet in a mode where the server purely functions as a simple file store and doesn’t index or process content on the server, you can do so by setting this environment variable to `true`. As a result, the client will always run in the Sync [[Client Modes|client mode]].
|
||||
|
||||
# Security
|
||||
$security
|
||||
|
||||
SilverBullet enables plugs to run shell commands. This is used by e.g. the [[🔌 Git]] plug to perform git commands. This is potentially unsafe. If you don’t need this, you can disable this functionality:
|
||||
|
||||
* `SB_SHELL_BACKEND`: Enable/disable running of shell commands from plugs, defaults to `local` (enabled), set to `off` to disable. It is only enabled when using a local folder for [[$storage]].
|
||||
|
||||
|
||||
# Docker
|
||||
Configuration only relevant to docker deployments:
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
> **warning** Experimental
|
||||
> This setup is not battle-tested, use it at your own risk
|
||||
|
||||
You can deploy SilverBullet to [Deno Deploy](https://deno.com/deploy) for free, and store space content in [Deno KV](https://deno.com/kv).
|
||||
You can deploy SilverBullet to [Deno Deploy](https://deno.com/deploy) for free, and store space content in [Deno KV](https://deno.com/kv). This is a convenient option to deploy SilverBullet in the cloud, without having to run or pay for a server.
|
||||
|
||||
# Steps
|
||||
Sign up for a (free) [Deno Deploy account](https://dash.deno.com/projects) and “Create an empty project” there.
|
||||
@@ -25,10 +25,12 @@ $ deno install -Arf https://deno.land/x/deploy/deployctl.ts
|
||||
To deploy, run:
|
||||
|
||||
```shell
|
||||
deployctl deploy -p=your-project --entrypoint=https://silverbullet.md/silverbullet.js --include= --prod
|
||||
$ deployctl deploy -p=your-project --entrypoint=https://silverbullet.md/silverbullet.js --include= --prod
|
||||
```
|
||||
|
||||
# Migrating and backing up content
|
||||
If you want to migrate content _from_ or _to_ your new Deploy-based space, you can use [[Sync]]. For this be sure to also configure a `SB_AUTH_TOKEN` variable.
|
||||
This will ask you to authenticate with your Deno Deploy account, and then deploy SilverBullet.
|
||||
|
||||
For backup purposes, it may be wise to synchronize your content regularly this way.
|
||||
# Migrating and backing up content
|
||||
This setup stores you [[Spaces]] content in Deno’s KV database, which is still a beta feature and not specifically designed for this purpose. Therefore it’s recommended to use something like [[Sync]] to make backups elsewhere.
|
||||
|
||||
For this, be sure to also configure a `SB_AUTH_TOKEN` variable.
|
||||
@@ -0,0 +1,48 @@
|
||||
The SilverBullet is implemented using a JavaScript runtime called [Deno](https://deno.com/) which is a lot like node.js, just... you know, better. And we like better.
|
||||
|
||||
To run SilverBullet directly on your host system (so not in a [[Install/Docker]] container), you need to install Deno [first following these instructions](https://deno.land/manual/getting_started/installation).
|
||||
|
||||
After having installed Deno, run:
|
||||
|
||||
```shell
|
||||
$ deno install -f --name silverbullet --unstable -A https://get.silverbullet.md
|
||||
```
|
||||
|
||||
You only have to do this once. This will download the currently _released_ version of SilverBullet onto your machine.
|
||||
|
||||
If you prefer to live on the _bleeding edge_, you can install using the following command instead:
|
||||
|
||||
```shell
|
||||
$ deno install -f --name silverbullet --unstable -A https://silverbullet.md/silverbullet.js
|
||||
```
|
||||
|
||||
Either command will install `silverbullet` into your `~/.deno/bin` folder (which should already be in your `$PATH` if you followed the Deno install instructions).
|
||||
|
||||
While you have [[Install/Configuration|options as to where and how to store your content]], the most straightforward way is to simply use a folder on disk.
|
||||
|
||||
After creating a folder, run the following command in your terminal:
|
||||
|
||||
```shell
|
||||
$ silverbullet <pages-path>
|
||||
```
|
||||
|
||||
By default, SilverBullet will bind to port `3000`; to use a different port, use the `-p` flag (e.g. `-p8080`).
|
||||
|
||||
For security reasons, by default, SilverBullet only allows connections via `localhost` (or `127.0.0.1`). To also allow connections from the network, pass a `-L0.0.0.0` flag (0.0.0.0 for all connections, or insert a specific address to limit the host), combined with `--user username:password` to add simple [[Authentication]].
|
||||
|
||||
Once downloaded and booted, SilverBullet will print out a URL to open in your browser.
|
||||
|
||||
# Upgrading
|
||||
SilverBullet is regularly updated. To get the latest and greatest, simply run:
|
||||
|
||||
```shell
|
||||
$ silverbullet upgrade
|
||||
```
|
||||
|
||||
And restart SilverBullet. You should be good to go.
|
||||
|
||||
Deno itself is also updated regularly, so be sure to let that self-upgrade as well:
|
||||
|
||||
```shell
|
||||
$ deno upgrade
|
||||
```
|
||||
@@ -0,0 +1,94 @@
|
||||
# Introduction
|
||||
[Docker](https://www.docker.com/) is a convenient and secure way to install server applications either locally or on a server you control. If you don’t have docker already running on your machine and are macOS user, consider giving [OrbStack](https://orbstack.dev/) a try — it’s a super nice docker experience.
|
||||
|
||||
Conveniently, SilverBullet is published as a [docker image on docker hub](https://hub.docker.com/r/zefhemel/silverbullet). The image comes in two flavors:
|
||||
|
||||
* 64-bit Intel
|
||||
* 64-bit ARM (e.g. for Raspberry Pis and Apple Silicon macs)
|
||||
|
||||
There is no 32-bit version of Deno, and therefore we cannot offer a 32-bit version of SilverBullet either. Most people run 64-bit OSes these days, an exception may be Raspberry Pis. Recent (RPI 3 and later) can run 64-bit Linux as well, you may have to re-image, though.
|
||||
|
||||
A few key things to know about the SilverBullet container image:
|
||||
* The container binds to port `3000`, so be sure to port-map that, e.g. via `-p 3000:3000` (note: the first `3000` is the external port)
|
||||
* The container uses whatever is volume-mapped to `/space` as the space root folder. You can connect a docker volume, or a host folder to this, e.g. `-v /home/myuser/space:/space`
|
||||
* SilverBullet will detect the UNIX owner (UID and GID) of the folder mapped into `/space` and run the server process with the same UID and GID so that permissions will just magically work. If you’d like to override this UID, set the `PUID` and `PGID` environment variables (see [[Install/Configuration]] for details).
|
||||
|
||||
# Setup
|
||||
For your first run, you can run the following:
|
||||
|
||||
```shell
|
||||
# Create a local folder "space" to keep files in
|
||||
$ mkdir -p space
|
||||
# Run the SilverBullet docker container in the foreground
|
||||
$ docker run -it -p 3000:3000 -v ./space:/space zefhemel/silverbullet
|
||||
```
|
||||
|
||||
This will run SilverBullet in the foreground, interactively, so you can see the logs and instructions.
|
||||
|
||||
If this all works fine, just kill the thing with `Ctrl-c` (don’t worry, it’s ok).
|
||||
|
||||
Now you probably want to run the container in daemon (background) mode, give it a name, and automatically have it restart after you e.g. reboot your machine:
|
||||
|
||||
```shell
|
||||
$ docker run -d --restart unless-stopped --name silverbullet -p 3000:3000 -v ./space:/space zefhemel/silverbullet
|
||||
```
|
||||
|
||||
There you go!
|
||||
|
||||
# Versions
|
||||
The `zefhemel/silverbullet` image will give you the latest released version. This is equivalent to `zefhemel/silverbullet:latest`. If you prefer, you can also pin to a specific release, e.g. `zefhemel/silverbullet:0.5.5`. If you prefer to live on the bleeding edge, you can use the `zefhemel/silverbullet:edge` image, which is updated on every commit to the `main` brain. This is the YOLO option.
|
||||
|
||||
## Upgrade
|
||||
You can upgrade SilverBullet as follows:
|
||||
|
||||
```shell
|
||||
# Pull the latest version of the image
|
||||
$ docker pull zefhemel/silverbullet
|
||||
# Kill the running container
|
||||
$ docker kill silverbullet
|
||||
# Remove the old container
|
||||
$ docker rm silverbullet
|
||||
# Start a fresh one (same command as before)
|
||||
$ docker run -d --restart unless-stopped --name silverbullet -p 3000:3000 -v ./space:/space zefhemel/silverbullet
|
||||
```
|
||||
|
||||
Since this is somewhat burdensome, it is recommended you use a tool like [watchtower](https://github.com/containrrr/watchtower) to automatically update your docker images and restart them. However, if we go there — we may as well use a tool like _docker compose_ to manage your containers, no?
|
||||
|
||||
# Docker compose
|
||||
[Docker compose](https://docs.docker.com/compose/) is a simple tool to manage running of multiple containers on a server you control. It’s like Kubernetes, but you know, not insanely complex.
|
||||
|
||||
Here is a simple `compose.yml` that runs SilverBullet as well as [watchtower](https://github.com/containrrr/watchtower), which will check for new SilverBullet upgrades daily (the default) and upgrade automatically.
|
||||
|
||||
Instructions:
|
||||
* Please replace the password defined in `SB_USER` with something sensible such as `admin:b3stp4ssword3vah`
|
||||
* This volume uses the `./space` directory (that presumably exists) in the same directory as the `compose.yml` file as the place where SB will keep its space.
|
||||
* Check out [[Install/Configuration]] for more interesting `environment` variables you can set.
|
||||
|
||||
```yaml
|
||||
services:
|
||||
silverbullet:
|
||||
image: zefhemel/silverbullet
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
- SB_USER="admin:admin"
|
||||
volumes:
|
||||
- ./space:/space
|
||||
ports:
|
||||
- 3000:3000
|
||||
watchtower:
|
||||
image: containrrr/watchtower
|
||||
volumes:
|
||||
- /var/run/docker.sock:/var/run/docker.sock
|
||||
```
|
||||
|
||||
Boot this up via:
|
||||
|
||||
```shell
|
||||
$ docker-compose up -d
|
||||
```
|
||||
|
||||
And watch for logs with:
|
||||
|
||||
```shell
|
||||
$ docker-compose logs -f
|
||||
```
|
||||
+2
-121
@@ -1,6 +1,6 @@
|
||||
Installing SilverBullet as a (local) web server is pretty straightforward, if you’re comfortable with the terminal, at least.
|
||||
Installing SilverBullet as a (local) web server is pretty straightforward if you’re technically inclined enough to be able to use a terminal.
|
||||
|
||||
The basic setup is simple: in a terminal, run the silverbullet server process on your machine, then connect to it locally from your browser via localhost.
|
||||
The basic setup is simple: in a terminal, run the silverbullet server process on your machine, then connect to it locally from your browser via `localhost`.
|
||||
|
||||
You have two options here:
|
||||
|
||||
@@ -9,122 +9,3 @@ You have two options here:
|
||||
|
||||
After choose either, be sure to checkout all [[Install/Configuration]] options as well.
|
||||
|
||||
# Installing using Deno
|
||||
$deno
|
||||
This consists of two steps (unless [Deno](https://deno.com/) is already installed — in which case we’re down to one):
|
||||
|
||||
1. [Install Deno](https://deno.land/manual/getting_started/installation)
|
||||
2. Install SilverBullet itself (steps below)
|
||||
|
||||
After having installed Deno ([instructions on its website](https://docs.deno.com/runtime/manual/getting_started/installation)) run:
|
||||
|
||||
```shell
|
||||
deno install -f --name silverbullet --unstable -A https://get.silverbullet.md
|
||||
```
|
||||
|
||||
You only have to do this once.
|
||||
|
||||
This will give you (and when you use `silverbullet upgrade`) the latest stable release. If you prefer to live on the bleeding edge, you can install using the following command instead:
|
||||
|
||||
```shell
|
||||
deno install -f --name silverbullet --unstable -A https://silverbullet.md/silverbullet.js
|
||||
```
|
||||
|
||||
Either command will install `silverbullet` into your `~/.deno/bin` folder (which should already be in your `$PATH` if you followed the Deno install instructions).
|
||||
|
||||
To run SilverBullet, create a folder for your pages (it can be empty or be an existing folder with `.md` files) and run the following command in your terminal:
|
||||
|
||||
```shell
|
||||
silverbullet <pages-path>
|
||||
```
|
||||
|
||||
By default, SilverBullet will bind to port `3000`; to use a different port, use the `-p` flag.
|
||||
|
||||
For security reasons, by default, SilverBullet only allows connections via `localhost` (or `127.0.0.1`). To also allow connections from the network, pass a `-L0.0.0.0` flag (0.0.0.0 for all connections, or insert a specific address to limit the host), combined with `--user username:password` to add simple [[Authentication]].
|
||||
|
||||
Once downloaded and booted, SilverBullet will print out a URL to open in your browser.
|
||||
|
||||
## Upgrading SilverBullet
|
||||
SilverBullet is regularly updated. To get the latest and greatest, simply run:
|
||||
|
||||
```shell
|
||||
silverbullet upgrade
|
||||
```
|
||||
|
||||
And restart SilverBullet. You should be good to go. Also run
|
||||
|
||||
```shell
|
||||
deno upgrade
|
||||
```
|
||||
|
||||
Regularly, to get the latest and greatest deno.
|
||||
|
||||
# Installing using Docker
|
||||
$docker
|
||||
There is a [docker image on docker hub](https://hub.docker.com/r/zefhemel/silverbullet). The image comes in two flavors:
|
||||
|
||||
* 64-bit Intel
|
||||
* 64-bit ARM (e.g. for Raspberry Pis and Macs)
|
||||
|
||||
There is no 32-bit version of Deno, and therefore we cannot offer a 32-bit version of SilverBullet either. Most people run 64-bit OSes these days, an exception may be Raspberry Pis. Recent (RPI 3 and later) can run 64-bit Linux as well, you may have to re-image, though.
|
||||
|
||||
A few key things to note on the SilverBullet container:
|
||||
* The container binds to port `3000`, so be sure to export that, e.g. via `-p 3000:3000` (note: the first `3000` is the external port)
|
||||
* The container uses whatever is volume-mapped to `/space` as the space root folder. You can connect a docker volume, or a host folder to this, e.g. `-v /home/myuser/space:/space`
|
||||
* SilverBullet will, conveniently, detect the UNIX owner (UID and GID) of the folder mapped into `/space` and run the server process with the same UID and GID so that permissions will just magically work. If you’d like to override this UID, set the `PUID` and `PGID` environment variables.
|
||||
|
||||
To boot up the container:
|
||||
|
||||
```shell
|
||||
docker run -p 3000:3000 -v /path/to/space/folder:/space -d zefhemel/silverbullet
|
||||
```
|
||||
|
||||
The `zefhemel/silverbullet` image will give you the latest released version. This is equivalent to `zefhemel/silverbullet:latest`. If you prefer, you can also pin to a specific release, e.g. `zefhemel/silverbullet:0.5.5`. If you prefer to live on the bleeding edge, you can use the `zefhemel/silverbullet:edge` image, which is updated on every commit to the `main` brain.
|
||||
|
||||
To configure various things such as authentication, use [[@env|environment variables]], e.g. to enable single-user auth:
|
||||
|
||||
```shell
|
||||
docker run -p 3000:3000 -v myspace:/space -d -e SB_USER=me:letmein zefhemel/silverbullet
|
||||
```
|
||||
|
||||
## Upgrade
|
||||
You can upgrade your image simply by pulling a new version of the image using `docker pull zefhemel/silverbullet`. However, it is recommended you use a tool like [watchtower](https://github.com/containrrr/watchtower) to automatically update your docker images and restart them.
|
||||
|
||||
## Docker compose
|
||||
Here is a simple `compose.yml` that runs SilverBullet as well as [watchtower](https://github.com/containrrr/watchtower), which will check for new SilverBullet upgrades daily (the default) and upgrade automatically.
|
||||
|
||||
Instructions:
|
||||
* Please replace the password defined in `SB_USER` with something sensible such as `admin:b3stp4ssword3vah`
|
||||
* This volume uses the `notes` directory (that presumably exists) in the same directory as the `compose.yml` file as the place where SB will keep its space.
|
||||
|
||||
```yaml
|
||||
services:
|
||||
silverbullet:
|
||||
image: zefhemel/silverbullet:edge
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
- SB_USER="admin:admin"
|
||||
volumes:
|
||||
- ./notes:/space
|
||||
ports:
|
||||
- 3000:3000
|
||||
watchtower:
|
||||
image: containrrr/watchtower
|
||||
volumes:
|
||||
- /var/run/docker.sock:/var/run/docker.sock
|
||||
```
|
||||
|
||||
Boot this up via:
|
||||
|
||||
```shell
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
And watch for logs with:
|
||||
|
||||
```shell
|
||||
docker-compose logs -f
|
||||
```
|
||||
|
||||
## Building the docker image
|
||||
To build your own version of the docker image, run `./scripts/build_docker.sh`.
|
||||
|
||||
@@ -1,13 +1,13 @@
|
||||
Running SilverBullet [[Install/Local|locally]] on your machine is cool, but you likely want to access it from elsewhere as well (other machines on your network, your mobile device), perhaps even from outside your home. For this you either need to use a VPN, or expose SB to the public Internet via _HTTPS_.
|
||||
Running SilverBullet locally on your machine is cool and all, but you likely want to access it from elsewhere as well (other machines on your network, your mobile device), perhaps even from outside your home. For this you either need to use a VPN, or expose SB to the public Internet via _HTTPS_.
|
||||
|
||||
In either scenario, be sure to enable some sort of [[Authentication]].
|
||||
|
||||
There’s two parts to this process:
|
||||
|
||||
1. Run the SilverBullet server itself somewhere, following the [[Install/Local]] instructions
|
||||
1. Run the SilverBullet server itself somewhere, following the [[Install]] instructions
|
||||
2. Exposing this server to the network/Internet
|
||||
|
||||
In all scenarios (that are not [[Install/Local]]) you _have_ to access SilverBullet via HTTPS otherwise certain features (such offline-support) won’t work.
|
||||
In all scenarios (that are not local) you _have_ to access SilverBullet via HTTPS, otherwise certain features (such offline-support) won’t work.
|
||||
|
||||
People have found various simple to more complex ways of achieving this.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user