Skip to content

Commit

Permalink
Simplify documentation on Docker installations
Browse files Browse the repository at this point in the history
  • Loading branch information
ohsayan committed Dec 29, 2023
1 parent e96f32a commit 2b3e045
Show file tree
Hide file tree
Showing 2 changed files with 32 additions and 11 deletions.
37 changes: 28 additions & 9 deletions docs/2.installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ title: Installation
Getting started with Skytable involves choosing a mode of installation, downloading any required files and then starting up the database. You can choose to either use:

- [**Native binaries (recommended)**](#native-binaries): This is what is generally recommended for the best performance. You will need to download a bundle and then start the server binary; no expert knowledge required
- [**Using a Debian package (recommended)**](#debian-package): If you're deploying on Ubuntu or any other Debian based Linux distribution, then consider using this method. Configuration files, users and passwords are autogenerated.
- [**Using a Debian package (recommended)**](#debian-package): If you're deploying on Ubuntu or any other Debian based Linux distribution, then consider using this method. Configuration files, users and passwords are autogenerated.
- [**A Docker image**](#docker-image): We generally recommend using a Docker image for experimenting with Skytable on your local system during development and you want to keep your local system *clean*. If you want to use a Docker image for deployment, you're always free to do so!
> **Note:** You might experience slightly degraded performance from the storage engine due to Docker engine's abstractions.
Expand All @@ -26,9 +26,11 @@ To use native binaries you need to download a bundle which is simply a ZIP file
- `skysh`: This is the Skytable shell and it provides a very helpful interactive REPL database client
- `sky-bench`: This is the benchmarking tool that you can use to load test Skytable
3. **Start up the server**. You need to choose a `root` password for the `root` account which will have complete control over the database.

```bash
./skyd --auth-root-password=<your root password> --auth-plugin=pwd
```

**Replace with your own secure password!**

Explanation:
Expand All @@ -40,38 +42,55 @@ The server starts up at `localhost:2003` and is ready to run queries.
## Debian package

Find the correct `*.deb` file [from the releases page](https://github.com/skytable/skytable/releases). Now simply run:

```sh
sudo dpkg -i <file name>.deb
```

The package will:

- **Generate a root password:** Watch the terminal output!
- **Create a `systemd` unit**: So you can start and stop the process using `systemd` like `systemd start skyd`
- **Generate a configuration**: Your configuration is stored in `/var/lib/skytable/config.yaml`. Go ahead and modify it if you need to!

## Docker image

:::info You must have docker set up!

- Use [this great guide from Docker](https://docs.docker.com/engine/install/) to install and get started
- To be able to run `docker run` and related commands, you may need administrative privileges
:::

### Simple setup

1. **Download the bundle**: To be able to run queries you need to download the bundle as described above
2. **Start the container**:

```shell
docker run -d --name skydb -p 2003:2003 skytable/skytable:latest
```

:::tip
The password for the Skytable instance on the Docker container is auto-generated Run `docker logs -f skydb` and you'll see a log
message with the generated password.
:::
### With persistence
1. **Download the bundle**: To be able to run queries you need to download the bundle as described above
2. **Create the data directory**: To ensure that our database is persistent and all our data doesn't vanish as soon as the container is terminated, we'll map the data directory to an actual directory on our local system.
> **Note:** Create a folder called `skytable` in a convenient location. We recommend having a directory in `$HOME/docker-containers` where you can store the Skytable container's data and any other containers that you might use. It's a great way to keep things organized.
3. **Start the container**:
3. **Create your configuration**: [Download this template file](https://raw.githubusercontent.com/skytable/skytable/next/examples/config-files/template.yaml) and place it into the directory you created. Update the password with your `root` password of choice.
4. **Start the container**:
```shell
docker run -d --name skydb \
-v /home/docker-containers/skytable:/var/lib/skytable \
-v $HOME/docker-containers/skytable:/var/lib/skytable \
-p 2003:2003 \
skytable/skytable:latest
```
**Replace with your own secure password!**
Explanation:
- This starts a container with name `skydb`
- It maps the folder (as discussed earlier) `/home/docker-containers/skytable` from your local file system to `/var/skytable` (in the container's file system)
- It maps the folder (as discussed earlier) `$HOME/docker-containers/skytable` from your local file system to `/var/skytable` (in the container's file system)
- Maps port `2003` on the host to the containers port `2003` so that you can use the command-line client `skysh` without having to inspect the container's IP address
:::tip
The password for the Skytable instance on the Docker container is auto-generated Run `docker logs -f skydb` and you'll see a log
message with the generated password.
:::
6 changes: 4 additions & 2 deletions docs/3.using-repl.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@ You can read more in the [configuration](system/configuration) page.
## Using the REPL

You will now see a welcome message and the REPL will prompt you to run something. Now is a good time to run `sysctl report status` which should just print out `(Okay)` in a cyan shade:

```sh
> sysctl report status
(Okay)
Expand All @@ -33,6 +34,7 @@ You will now see a welcome message and the REPL will prompt you to run something
You can also run queries like: `inspect global` to see available global system information.

:::info Quick notes

- The REPL currently stores history in the `.sky_history` file. If you want to remove history, you can simply delete the file
- The REPL will automatically parameterize queries. Don't worry about what this means; you'll learn about it ahead.
- The REPL applies custom formatting to `DDL` queries. For example, even though `inspect global` returns a JSON as a string,
Expand All @@ -42,7 +44,7 @@ the REPL formats it and outputs it without quotes, to improve readability

## First steps

Skytable's data model is discussed in depth on [this page](architecture#data-model), but let us understand some basics. If you've used a SQL
Skytable's data model is discussed in depth on [this page](architecture#data-model), but let us understand some basics. If you've used a SQL
database, you would be used to the idea of a `database` &mdash; just like this, Skytable has `space`s. A `space` is a collection
of `models` (which are like SQL's `table`s with slightly different functionality) and other containers.

Expand Down Expand Up @@ -76,6 +78,6 @@ CREATE MODEL myspace.mymodel(username: string, password: string, notes: list { t

```sql
INSERT INTO myspace.mymodel('sayan', 'password123', [])
UPDATE myspace.mymodel SET notes += "mynewnote"
UPDATE myspace.mymodel SET notes += "mynewnote" WHERE username = 'sayan'
SELECT notes, password FROM myspace.mymodel WHERE username = 'sayan'
```

0 comments on commit 2b3e045

Please sign in to comment.