|
| 1 | +--- |
| 2 | +id: installation |
| 3 | +title: Installation |
| 4 | +--- |
| 5 | + |
| 6 | +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: |
| 7 | + |
| 8 | +- [**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 |
| 9 | +- [**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. |
| 10 | +- [**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! |
| 11 | + > **Note:** You might experience slightly degraded performance from the storage engine due to Docker engine's abstractions. |
| 12 | +
|
| 13 | +## Native binaries |
| 14 | + |
| 15 | +To use native binaries you need to download a bundle which is simply a ZIP file with all the necessary binaries that you'll ever need to develop on and deploy Skytable. |
| 16 | + |
| 17 | +1. **First download the latest bundle** for your platform. You can find [download links on the releases page](https://github.com/skytable/skytable/releases). |
| 18 | +2. **Unzip the ZIP file**. You'll find the following binaries in the extracted archive: |
| 19 | + - `skyd`: This is the database server binary which when started runs as a daemon, serving requests |
| 20 | + - `skysh`: This is the Skytable shell and it provides a very helpful interactive REPL database client |
| 21 | + - `sky-bench`: This is the benchmarking tool that you can use to load test Skytable |
| 22 | +3. **Start up the server**. You need to choose a `root` password for the `root` account which will have complete control over the database. |
| 23 | + |
| 24 | + ```bash |
| 25 | + ./skyd --auth-root-password=<your root password> |
| 26 | + ``` |
| 27 | + |
| 28 | + **Replace with your own secure password!** |
| 29 | + |
| 30 | + Explanation: |
| 31 | + - `--auth-root-password`: sets the root password |
| 32 | + |
| 33 | +The server starts up at `localhost:2003` and is ready to run queries. |
| 34 | + |
| 35 | +:::info |
| 36 | +Your operating system might sometimes not let you run binaries directly. On Unix based systems, you'll need to run: `chmod +x skyd skysh sky-bench`. |
| 37 | +
|
| 38 | +And on Windows systems you might need to right-click on the binaries and click on "unblock" |
| 39 | +::: |
| 40 | +
|
| 41 | +## Debian package |
| 42 | +
|
| 43 | +Find the correct `*.deb` file [from the releases page](https://github.com/skytable/skytable/releases). Now simply run: |
| 44 | +
|
| 45 | +```sh |
| 46 | +sudo dpkg -i <file name>.deb |
| 47 | +``` |
| 48 | +
|
| 49 | +The package will: |
| 50 | +
|
| 51 | +- **Generate a root password:** Watch the terminal output! |
| 52 | +- **Create a `systemd` unit**: So you can start and stop the process using `systemd` like `systemd start skyd` |
| 53 | +- **Generate a configuration**: Your configuration is stored in `/var/lib/skytable/config.yaml`. Go ahead and modify it if you need to! |
| 54 | +
|
| 55 | +## Docker image |
| 56 | +
|
| 57 | +:::info You must have docker set up! |
| 58 | +
|
| 59 | +- Use [this great guide from Docker](https://docs.docker.com/engine/install/) to install and get started |
| 60 | +- To be able to run `docker run` and related commands, you may need administrative privileges |
| 61 | +::: |
| 62 | +
|
| 63 | +### Simple setup |
| 64 | +
|
| 65 | +1. **Download the bundle**: To be able to run queries you need to download the bundle as described above |
| 66 | +2. **Start the container**: |
| 67 | +
|
| 68 | + ```shell |
| 69 | + docker run -d --name skydb -p 2003:2003 skytable/skytable:latest |
| 70 | + ``` |
| 71 | +
|
| 72 | +:::tip |
| 73 | +The password for the Skytable instance on the Docker container is auto-generated. Run `docker logs -f skydb` and you'll see a log |
| 74 | +message with the generated password. |
| 75 | +::: |
| 76 | + |
| 77 | +### With persistence |
| 78 | + |
| 79 | +1. **Download the bundle**: To be able to run queries you need to download the bundle as described above |
| 80 | +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. |
| 81 | + > **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. |
| 82 | +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. |
| 83 | +4. **Start the container**: |
| 84 | + |
| 85 | + ```shell |
| 86 | + docker run -d --name skydb \ |
| 87 | + -v $HOME/docker-containers/skytable:/var/lib/skytable \ |
| 88 | + -p 2003:2003 \ |
| 89 | + skytable/skytable:latest |
| 90 | + ``` |
| 91 | + |
| 92 | + Explanation: |
| 93 | + - This starts a container with name `skydb` |
| 94 | + - 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) |
| 95 | + - 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 |
0 commit comments