Skip to content

Commit

Permalink
Replace file with rocksdb, notes on --unauthenticated (#871)
Browse files Browse the repository at this point in the history 
Co-authored-by: Obinna Ekwuno <[email protected]>
  • Loading branch information
@Dhghomon @Ekwuno
Dhghomon and Ekwuno authored Sep 20, 2024
1 parent f3f00e2 commit 0843cb2
Show file tree
Hide file tree
Showing 5 changed files with 121 additions and 16 deletions.
84 changes: 84 additions & 0 deletions src/content/doc-surrealdb/cli/start.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@ description: The start command starts a SurrealDB server in memory, on disk, or
---
import Since from '@components/Since.astro'
import Label from "@components/shared/Label.astro";
import Tabs from "@components/Tabs/Tabs.astro";
import TabItem from "@components/Tabs/TabItem.astro";

# Start command

Expand All @@ -16,6 +18,85 @@ The start command starts a SurrealDB server in memory, on disk, or in a distribu
## Command options

<Tabs groupId="surreal-start">

<TabItem value="V1" label="V1.x" >
<table>
<thead>
<tr>
<th colspan="2">Arguments</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td colspan="2">
<code>-b</code> / <code>--bind</code>
<Label label="optional" />
</td>
<td>
Sets the hostname or IP address to listen for connections on
</td>
</tr>
<tr>
<td colspan="2">
<code>-l</code> / <code>--log</code>
<Label label="optional" />
</td>
<td>
Sets the logging level for the database server
</td>
</tr>
<tr>
<td colspan="2">
<code>-u</code> / <code>--user</code>
<Label label="optional" />
</td>
<td>
Sets master username for the database
</td>
</tr>
<tr>
<td colspan="2">
<code>-p</code> / <code>--pass</code>
<Label label="optional" />
</td>
<td>
Sets master password for the database
</td>
</tr>
<tr>
<td colspan="2">
<code>--auth</code>
<Label label="optional" />
</td>
<td>
Sets authentication to enabled
</td>
</tr>
<tr>
<td colspan="2">
<code>--no-identification-headers</code>
<Label label="optional" />
</td>
<td>
Whether to suppress the server name and version headers
</td>
</tr>
<tr>
<td colspan="2">
<code>-s</code> / <code>--strict</code>
<Label label="optional" />
</td>
<td>
Sets whether strict mode is enabled on this database instance
</td>
</tr>
</tbody>
</table>
</TabItem>

<TabItem value="V2" label="V2.x" >
<table>
<thead>
<tr>
Expand Down Expand Up @@ -89,6 +170,9 @@ The start command starts a SurrealDB server in memory, on disk, or in a distribu
</tr>
</tbody>
</table>
</TabItem>

</Tabs>

## Positional argument

Expand Down
2 changes: 1 addition & 1 deletion src/content/doc-surrealdb/deployment/amazon.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -243,7 +243,7 @@ curl -O https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-cont
aws iam create-policy \
--policy-name AWSLoadBalancerControllerIAMPolicy \
--policy-document file://iam_policy.json
--policy-document rocksdb://iam_policy.json
eksctl create iamserviceaccount \
--cluster=$CLUSTER_NAME \
Expand Down
18 changes: 10 additions & 8 deletions src/content/doc-surrealdb/installation/running/docker.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,40 +38,42 @@ In order to persist data when the Docker instance is restarted or shutdown, spec

```bash
mkdir mydata # Create a directory to store the database, owned by the current user
docker run --rm --pull always -p 8000:8000 --user $(id -u) -v $(pwd)/mydata:/mydata surrealdb/surrealdb:latest start file:/mydata/mydatabase.db
docker run --rm --pull always -p 8000:8000 --user $(id -u) -v $(pwd)/mydata:/mydata surrealdb/surrealdb:latest start rocksdb:/mydata/mydatabase.db
```

The default logging level for the database server is `info`, resulting in any informational logs to be output to the standard output. To control the logging verbosity, specify the *`--log`* argument. The following command starts the database with `trace` level logging, resulting in most logs being output to the terminal.

```bash
mkdir mydata # Create a directory to store the database, owned by the current user
docker run --rm --pull always -p 8000:8000 --user $(id -u) -v $(pwd)/mydata:/mydata surrealdb/surrealdb:latest start --log trace file:/mydata/mydatabase.db
docker run --rm --pull always -p 8000:8000 --user $(id -u) -v $(pwd)/mydata:/mydata surrealdb/surrealdb:latest start --log trace rocksdb:/mydata/mydatabase.db
```

### Configuring authentication

In order to keep SurrealDB secure, configure your initial root-level user by setting the *`--user`* and *`--pass`* command-line arguments. Authentication is required by default.
Authentication is enabled by default since version `2.0`, using the `--unauthenticated` flag to opt out. In versions of SurrealDB before 2.0, authentication was disabled by default and required an `--auth` flag to enable.

To set up access as an authenticated user, configure your initial root-level user by setting the *`--user`* and *`--pass`* command-line arguments.

The following command starts the database with a top-level user named `root` with a password also set to `root`. The root user will be persisted in storage, which means you don't have to include the command line arguments next time you start SurrealDB.

```bash
docker run --rm --pull always -p 80:8000 -v /mydata:/mydata surrealdb/surrealdb:latest start --log trace --user root --pass root file:mydatabase.db
docker run --rm --pull always -p 80:8000 -v /mydata:/mydata surrealdb/surrealdb:latest start --log trace --user root --pass root rocksdb:mydatabase.db
```

In order to change the default port that SurrealDB uses for web connections and from database clients you can use the Docker *`-p`* command line argument to tunnel the port to the internal SurrealDB port which SurrealDB is served on. The following command starts the database on port `80`.

```bash
docker run --rm --pull always -p 80:8000 -v /mydata:/mydata surrealdb/surrealdb:latest start --log trace --user root --pass root file:/mydata/mydatabase.db
docker run --rm --pull always -p 80:8000 -v /mydata:/mydata surrealdb/surrealdb:latest start --log trace --user root --pass root rocksdb:/mydata/mydatabase.db
```

After running the above command, you should see the SurrealDB server startup successfully.

```bash
docker run --rm --pull always -p 80:8000 -v /local-dir:/container-dir surrealdb/surrealdb:latest start --user root --pass root file:/container-dir/mydatabase.db
docker run --rm --pull always -p 80:8000 -v /local-dir:/container-dir surrealdb/surrealdb:latest start --user root --pass root rocksdb:/container-dir/mydatabase.db

2023-08-30T15:06:34.788739Z INFO surreal::dbs: ✅🔒 Authentication is enabled 🔒✅
2023-08-30T15:06:34.788821Z INFO surrealdb::kvs::ds: Starting kvs store in file:/container-dir/mydatabase.db
2023-08-30T15:06:34.788859Z INFO surrealdb::kvs::ds: Started kvs store in file:/container-dir/mydatabase.db
2023-08-30T15:06:34.788821Z INFO surrealdb::kvs::ds: Starting kvs store in rocksdb:/container-dir/mydatabase.db
2023-08-30T15:06:34.788859Z INFO surrealdb::kvs::ds: Started kvs store in rocksdb:/container-dir/mydatabase.db
2023-08-30T15:06:34.789222Z INFO surrealdb::kvs::ds: Initial credentials were provided and no existing root-level users were found: create the initial user 'root'.
2023-08-30T15:06:35.205123Z INFO surrealdb::node: Started node agent
2023-08-30T15:06:35.205827Z INFO surrealdb::net: Started web server on 0.0.0.0:8080
Expand Down
18 changes: 12 additions & 6 deletions src/content/doc-surrealdb/installation/running/file.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,30 +10,36 @@ description: For the purposes of getting started with SurrealDB quickly, we will
For the purposes of getting started with SurrealDB quickly, we will start a RocksDB database which persists data on the filesystem. This configuration is great for trying out the database and small deployments.

```bash
surreal start file:mydatabase.db
surreal start rocksdb:mydatabase.db
```

The default logging level for the database server is `info`, resulting in any informational logs to be output to the standard output. To control the logging verbosity, specify the *`--log`* argument. The following command starts the database with `trace` level logging, resulting in most logs being output to the terminal.

```bash
surreal start --log trace file:mydatabase.db
surreal start --log trace rocksdb:mydatabase.db
```

In order to keep SurrealDB secure, configure your initial root-level user by setting the *`--user`* and *`--pass`* command-line arguments. The following command starts the database with a top-level user named root with a password also set to `root`. The root user will be persisted in storage, which means you don't have to include the command line arguments next time you start SurrealDB.
In versions of SurrealDB before 2.0.0, anyone would be able to connect to this server to begin running queries. However, SurrealDB since version 2.0.0 runs with authentication by default. In order to disable it, the `--unauthenticated` flag can be passed in.

```bash
surreal start --log trace --user root --pass root file:mydatabase.db
surreal start --log trace --unauthenticated rocksdb:mydatabase.db
```

However, for anything but simple testing, it is better to configure your initial root-level user by setting the *`--user`* and *`--pass`* command-line arguments. The following command starts the database with a top-level user named root with a password also set to `root`. The root user will be persisted in storage, which means you don't have to include the command line arguments next time you start SurrealDB.

```bash
surreal start --log trace --user root --pass root rocksdb:mydatabase.db
```

In order to change the default port that SurrealDB uses for web connections and from database clients you can use the *`--bind`* argument. The following command starts the database on port `8080`.

```bash
surreal start --log trace --user root --pass root --bind 0.0.0.0:8080 file://path/to/mydatabase
surreal start --log trace --user root --pass root --bind 0.0.0.0:8080 rocksdb://path/to/mydatabase
```
After running the above command, you should see the SurrealDB server startup successfully.

```bash
surreal start --user root --pass root --bind 0.0.0.0:8080 file:mydatabase.db
surreal start --user root --pass root --bind 0.0.0.0:8080 rocksdb:mydatabase.db
2023-08-30T15:06:34.788739Z INFO surreal::dbs: ✅🔒 Authentication is enabled 🔒✅
2023-08-30T15:06:34.788821Z INFO surrealdb::kvs::ds: Starting kvs store in file:mydatabase.db
2023-08-30T15:06:34.788859Z INFO surrealdb::kvs::ds: Started kvs store in file:mydatabase.db
Expand Down
15 changes: 14 additions & 1 deletion src/content/doc-surrealdb/installation/running/memory.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,13 +13,25 @@ For the purposes of getting started with SurrealDB quickly, we will start an in-
surreal start memory
```

SurrealDB will assume `memory` in case this argument is not passed in, so the following command is identical to the above.

```bash
surreal start
```

The default logging level for the database server is `info`, resulting in any informational logs to be output to the standard output. To control the logging verbosity, specify the *`--log`* argument. The following command starts the database with `trace` level logging, resulting in most logs being output to the terminal.

```bash
surreal start --log trace memory
```

In order to keep SurrealDB secure, configure your initial root-level user by setting the *`--user`* and *`--pass`* command-line arguments. The following command starts the database with a top-level user named `root` with a password also set to `root`.
In versions of SurrealDB before `2.0`, anyone would be able to connect to this server to begin running queries. However, SurrealDB since version `2.0` runs with authentication by default. In order to disable it, the `--unauthenticated` flag can be passed in.

```bash
surreal start --log trace --unauthenticated memory
```

However, for anything but simple testing, it is better to configure your initial root-level user by setting the *`--user`* and *`--pass`* command-line arguments. The following command starts the database with a top-level user named `root` with a password also set to `root`.

```bash
surreal start --log trace --user root --pass root memory
Expand All @@ -46,4 +58,5 @@ surreal start --user root --pass root --bind 0.0.0.0:8080 memory
2023-08-30T15:06:35.205123Z INFO surrealdb::node: Started node agent
2023-08-30T15:06:35.205827Z INFO surrealdb::net: Started web server on 0.0.0.0:8080
```

For details on the different commands available, visit the [CLI tool documentation](/docs/surrealdb/cli).

0 comments on commit 0843cb2

Please sign in to comment.