-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
AUTO: Sync ScalarDL docs in English to docs site repo
- Loading branch information
Showing
1 changed file
with
221 additions
and
68 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,75 +1,228 @@ | ||
| # How to install ScalarDL in your local environment with Docker | ||
| # How to Install ScalarDL in Your Local Environment with Docker | ||
|
|
||
| This document shows how to set up a local environment that runs ScalarDL | ||
| along with the back-end Cassandra server using [Docker | ||
| Compose](https://docs.docker.com/compose/). | ||
| import Tabs from '@theme/Tabs'; | ||
| import TabItem from '@theme/TabItem'; | ||
| import WarningLicenseKeyContact from '/src/components/en-us/_warning-license-key-contact.mdx'; | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| - [Docker Engine](https://docs.docker.com/engine/) and [Docker Compose](https://docs.docker.com/compose/). | ||
|
|
||
| Follow the instructions on the Docker website according to your platform. | ||
|
|
||
|
|
||
| ## Clone scalardl-samples repository | ||
|
|
||
| [scalar-labs/scalardl-samples](https://github.com/scalar-labs/scalardl-samples) | ||
| repository is a project for users to start working on ScalarDL instantly. | ||
|
|
||
| Determine the location on your local machine where you want to run the | ||
| scalardl-samples app. Then open the terminal and `cd` to the directory and run the | ||
| following commands: | ||
|
|
||
| ```console | ||
| git clone https://github.com/scalar-labs/scalardl-samples.git | ||
| cd scalardl-samples | ||
| ``` | ||
|
|
||
| ## Docker login | ||
|
|
||
| `docker login` is required to start the ScalarDL Docker image. Because the | ||
| [`scalar-ledger`](https://github.com/orgs/scalar-labs/packages/container/package/scalar-ledger) repository | ||
| on GitHub Container Registry is currently private, your GitHub account needs to be set with permissions to access the container images. | ||
| Ask a person in charge to get your account ready. Note also that you need to use a personal access token (PAT) as a password to login `ghcr.io`. Please read [the official document](https://docs.github.com/en/packages/guides/migrating-to-github-container-registry-for-docker-images#authenticating-with-the-container-registry) for more detail. | ||
| This document shows how to set up a local environment that runs ScalarDL along with the back-end Cassandra server using [Docker Compose](https://docs.docker.com/compose/). | ||
|
|
||
| ```console | ||
| # read:packages scope needs to be selected in a personal access token to login | ||
| export CR_PAT=YOUR_PERSONAL_ACCESS_TOKEN | ||
| echo $CR_PAT | docker login ghcr.io -u USERNAME --password-stdin | ||
| ``` | ||
| <WarningLicenseKeyContact product="ScalarDL" /> | ||
|
|
||
| ## Start up ScalarDL Ledger | ||
|
|
||
| The following command starts up ScalarDL Ledger along with the back-end Cassandra server in the Docker containers. At the first time you run the command, the required Docker images will be downloaded from GitHub Container Registry. | ||
|
|
||
| ```console | ||
| docker-compose up | ||
| ``` | ||
|
|
||
| You may want to run the containers in the background. Add the `-d` (`--detach`) option: | ||
|
|
||
| ```console | ||
| docker-compose up -d | ||
| ``` | ||
|
|
||
| When you want to use Auditor component, run the following command. | ||
|
|
||
| ```console | ||
| docker-compose -f docker-compose.yml -f docker-compose-auditor.yml up -d | ||
|
|
||
| ``` | ||
|
|
||
| ## Shut down ScalarDL Ledger | ||
|
|
||
| To shut down the containers: | ||
| ## Prerequisites | ||
|
|
||
| - If you started the containers in the foreground, type `Ctrl+C` in the terminal | ||
| where `docker-compose` is running. | ||
| - If you started the containers in the background, run the following command. | ||
| - [Docker](https://www.docker.com/get-started/) 20.10 or later with [Docker Compose](https://docs.docker.com/compose/install/) V2 or later | ||
|
|
||
| ```console | ||
| docker-compose down | ||
| Follow the instructions on the Docker website according to your platform. | ||
|
|
||
| # When Auditor is running | ||
| docker-compose -f docker-compose.yml -f docker-compose-auditor.yml down | ||
| ``` | ||
| ## Clone the scalardl-samples repository | ||
|
|
||
| The [scalar-labs/scalardl-samples](https://github.com/scalar-labs/scalardl-samples) repository includes sample applications for you to start using ScalarDL instantly. | ||
|
|
||
| 1. In Terminal, determine the location on your local machine where you want to run the `scalardl-samples` app. Then, clone the `scalardl-samples` repository. | ||
|
|
||
| ```console | ||
| git clone https://github.com/scalar-labs/scalardl-samples.git | ||
| ``` | ||
|
|
||
| 1. Go to the `scalardl-samples` directory. | ||
|
|
||
| ```console | ||
| cd scalardl-samples | ||
| ``` | ||
|
|
||
| ## Set your license key | ||
|
|
||
| <Tabs groupId="modes" queryString> | ||
| <TabItem value="ledger-only" label="ScalarDL Ledger only" default> | ||
| <h3>Set your license key for ScalarDL Ledger</h3> | ||
| You must set your license key for ScalarDL Ledger. In the `docker-compose.yml` file, please replace `<SET_YOUR_LICENSE_KEY>` with your license key. For example: | ||
|
|
||
| ```yaml | ||
| services: | ||
| scalar-ledger: | ||
| environment: | ||
| - SCALAR_DL_LICENSING_LICENSE_KEY={"organization_name":"XXXXXXXX","expiration_date_time":"YYYY-MM-DDTHH:mm:SS+TIMEZONE","product_name":"ScalarDL Ledger","product_version":N,"license_type":"trial","signature":"XXXXXXXX"} | ||
| ``` | ||
| </TabItem> | ||
| <TabItem value="auditor-mode" label="ScalarDL Auditor mode"> | ||
| <h3>Set your license key for ScalarDL Ledger</h3> | ||
| You must set your license key for ScalarDL Ledger. In the `docker-compose.yml` file, please replace `<SET_YOUR_LICENSE_KEY>` with your license key. For example: | ||
|
|
||
| ```yaml | ||
| services: | ||
| scalar-ledger: | ||
| environment: | ||
| - SCALAR_DL_LICENSING_LICENSE_KEY={"organization_name":"XXXXXXXX","expiration_date_time":"YYYY-MM-DDTHH:mm:SS+TIMEZONE","product_name":"ScalarDL Ledger","product_version":N,"license_type":"trial","signature":"XXXXXXXX"} | ||
| ``` | ||
|
|
||
| <h3>Set your license key for ScalarDL Auditor</h3> | ||
|
|
||
| You must set your license key for ScalarDL Auditor. In the `docker-compose-auditor.yml` file, please replace `<SET_YOUR_LICENSE_KEY>` with your license key. For example: | ||
|
|
||
| ```yaml | ||
| services: | ||
| scalar-auditor: | ||
| environment: | ||
| - SCALAR_DL_LICENSING_LICENSE_KEY={"organization_name":"XXXXXXXX","expiration_date_time":"YYYY-MM-DDTHH:mm:SS+TIMEZONE","product_name":"ScalarDL Auditor","product_version":N,"license_type":"trial","signature":"XXXXXXXX"} | ||
| ``` | ||
| </TabItem> | ||
| </Tabs> | ||
|
|
||
| ## Set the certificate file for checking the license key | ||
|
|
||
| :::note | ||
|
|
||
| If you have a trial license, you can skip this step and [start up ScalarDL](#start-up-scalardl). | ||
|
|
||
| ::: | ||
|
|
||
| <Tabs groupId="modes" queryString> | ||
| <TabItem value="ledger-only" label="ScalarDL Ledger only" default> | ||
| In this step, you must set the certificate file for ScalarDL Ledger. | ||
| <h3>Set the certificate file for ScalarDL Ledger</h3> | ||
| If you have a commercial license, you must update the `docker-compose.yml` file as follows: | ||
|
|
||
| - Before changing the certificate file path (default configuration): | ||
|
|
||
| ```yaml | ||
| services: | ||
| scalar-ledger: | ||
| volumes: | ||
| - ./fixture/ledger-key.pem:/scalar/ledger-key.pem | ||
| - ./fixture/ledger.properties.tmpl:/scalar/ledger/ledger.properties.tmpl | ||
| - ./fixture/trial-license-cert.pem:/scalar/license-cert.pem | ||
| # If you have a commercial license key, you must use `commercial-license-cert.pem` instead of `trial-license-cert.pem`. | ||
| # - ./fixture/commercial-license-cert.pem:/scalar/license-cert.pem | ||
| ``` | ||
|
|
||
| - After changing the certificate file path: | ||
|
|
||
| ```yaml | ||
| services: | ||
| scalar-ledger: | ||
| volumes: | ||
| - ./fixture/ledger-key.pem:/scalar/ledger-key.pem | ||
| - ./fixture/ledger.properties.tmpl:/scalar/ledger/ledger.properties.tmpl | ||
| # - ./fixture/trial-license-cert.pem:/scalar/license-cert.pem | ||
| # If you have a commercial license key, you must use `commercial-license-cert.pem` instead of `trial-license-cert.pem`. | ||
| - ./fixture/commercial-license-cert.pem:/scalar/license-cert.pem | ||
| ``` | ||
| </TabItem> | ||
| <TabItem value="auditor-mode" label="ScalarDL Auditor mode"> | ||
| In this step, you must set the certificate file for ScalarDL Ledger and ScalarDL Auditor. | ||
|
|
||
| <h3>Set the certificate file for ScalarDL Ledger</h3> | ||
| If you have a commercial license, you must update the `docker-compose.yml` file as follows: | ||
|
|
||
| - Before changing the certificate file path (default configuration): | ||
|
|
||
| ```yaml | ||
| services: | ||
| scalar-ledger: | ||
| volumes: | ||
| - ./fixture/ledger-key.pem:/scalar/ledger-key.pem | ||
| - ./fixture/ledger.properties.tmpl:/scalar/ledger/ledger.properties.tmpl | ||
| - ./fixture/trial-license-cert.pem:/scalar/license-cert.pem | ||
| # If you have a commercial license key, you must use `commercial-license-cert.pem` instead of `trial-license-cert.pem`. | ||
| # - ./fixture/commercial-license-cert.pem:/scalar/license-cert.pem | ||
| ``` | ||
|
|
||
| - After changing the certificate file path: | ||
|
|
||
| ```yaml | ||
| services: | ||
| scalar-ledger: | ||
| volumes: | ||
| - ./fixture/ledger-key.pem:/scalar/ledger-key.pem | ||
| - ./fixture/ledger.properties.tmpl:/scalar/ledger/ledger.properties.tmpl | ||
| # - ./fixture/trial-license-cert.pem:/scalar/license-cert.pem | ||
| # If you have a commercial license key, you must use `commercial-license-cert.pem` instead of `trial-license-cert.pem`. | ||
| - ./fixture/commercial-license-cert.pem:/scalar/license-cert.pem | ||
| ``` | ||
|
|
||
| <h3>Set the certificate file for ScalarDL Auditor</h3> | ||
|
|
||
| If you have a commercial license, you must update the `docker-compose-auditor.yml` file as follows: | ||
|
|
||
| - Before changing the certificate file path (default configuration): | ||
|
|
||
| ```yaml | ||
| services: | ||
| scalar-auditor: | ||
| volumes: | ||
| - ./fixture/auditor.pem:/scalar/auditor.pem | ||
| - ./fixture/auditor-key.pem:/scalar/auditor-key.pem | ||
| - ./fixture/auditor.properties.tmpl:/scalar/auditor/auditor.properties.tmpl | ||
| - ./fixture/trial-license-cert.pem:/scalar/license-cert.pem | ||
| # If you have a commercial license key, you must use `commercial-license-cert.pem` instead of `trial-license-cert.pem`. | ||
| # - ./fixture/commercial-license-cert.pem:/scalar/license-cert.pem | ||
| ``` | ||
|
|
||
| - After changing the certificate file path: | ||
|
|
||
| ```yaml | ||
| services: | ||
| scalar-auditor: | ||
| volumes: | ||
| - ./fixture/auditor.pem:/scalar/auditor.pem | ||
| - ./fixture/auditor-key.pem:/scalar/auditor-key.pem | ||
| - ./fixture/auditor.properties.tmpl:/scalar/auditor/auditor.properties.tmpl | ||
| # - ./fixture/trial-license-cert.pem:/scalar/license-cert.pem | ||
| # If you have a commercial license key, you must use `commercial-license-cert.pem` instead of `trial-license-cert.pem`. | ||
| - ./fixture/commercial-license-cert.pem:/scalar/license-cert.pem | ||
| ``` | ||
| </TabItem> | ||
| </Tabs> | ||
|
|
||
| ## Start up ScalarDL | ||
|
|
||
| <Tabs groupId="modes" queryString> | ||
| <TabItem value="ledger-only" label="ScalarDL Ledger only" default> | ||
| The following command starts up ScalarDL Ledger, along with the backend Cassandra server in the Docker containers. | ||
| :::note | ||
|
|
||
| The first time you run this command, the required Docker images will be downloaded from GitHub Container Registry. | ||
|
|
||
| ::: | ||
|
|
||
| ```console | ||
| docker compose up -d | ||
| ``` | ||
| </TabItem> | ||
| <TabItem value="auditor-mode" label="ScalarDL Auditor mode"> | ||
| The following command starts up ScalarDL Ledger and ScalarDL Auditor, along with the backend Cassandra server in the Docker containers. | ||
| :::note | ||
|
|
||
| The first time you run this command, the required Docker images will be downloaded from GitHub Container Registry. | ||
|
|
||
| ::: | ||
|
|
||
| ```console | ||
| docker compose -f docker-compose.yml -f docker-compose-auditor.yml up -d | ||
| ``` | ||
| </TabItem> | ||
| </Tabs> | ||
|
|
||
| ## Shut down ScalarDL | ||
|
|
||
| To shut down the containers, run the following command. | ||
|
|
||
| <Tabs groupId="modes" queryString> | ||
| <TabItem value="ledger-only" label="ScalarDL Ledger only" default> | ||
| ```console | ||
| docker compose down -v | ||
| ``` | ||
| </TabItem> | ||
| <TabItem value="auditor-mode" label="ScalarDL Auditor mode"> | ||
| ```console | ||
| docker compose -f docker-compose.yml -f docker-compose-auditor.yml down -v | ||
| ``` | ||
| </TabItem> | ||
| </Tabs> |