Files

Nadav Har'El 70d914ad5b alternator: update docker instructions in docs/alternator/getting-started.md

The instructions in docs/alternator/getting-started.md on how to run
Alternator with docker are outdated and confusing, so this patch updates
them.

First, the instructions recommended the scylladb/scylla-nightly:alternator
tag, but we only ever created this tag once, and never updated it. Since
then, Alternator has been constantly improving, and we've caught up on
a lot of features, and people who want to test or evaluate Alternator
will most likely want to run the latest nightly build, with all the latest
Alternator features. So we update the instructions to request the latest
nightly build - and mention the need to explictly do "docker pull" (without
this step, you can find yourself running an antique nightly build, which
you downloaded months ago!). This instruction can be revisited once
Alternator is GAed and not improving quickly and we can then recommend to
run the latest stable Scylla - but I think we're not there yet.

Second, in recent builds, Alternator requires that the LWT feature is
enabled, and since LWT is still experimental, this means that one needs
to add "--experimental 1" to the "docker run" command. Without it, the
command line in getting-started.md will refuse to boot, complaining that
Alternator was enabled but LWT wasn't. So this patch adds the
"--experimental 1" in the relevant places in the text. Again, this
instruction can and should be revisited once LWT goes out of experimental
mode.

Fixes #5813

Signed-off-by: Nadav Har'El <nyh@scylladb.com>
Message-Id: <20200216113601.9535-1-nyh@scylladb.com>

2020-02-16 12:42:37 +01:00

3.5 KiB

Raw Blame History

Getting Started With ScyllaDB Alternator

Installing Scylla

Before you can start using ScyllaDB Alternator, you will have to have an up and running scylla cluster configured to expose the alternator port. This section will guide you through the steps for setting up the cluster:

Get Scylla with alternator support from a docker:

Because Alternator is still experimental and improves quickly, it is recommended to run the latest nightly build. Make sure you have the latest nightly image by running: docker pull scylladb/scylla-nightly:latest
Follow the steps in the Scylla official download web page add to every "docker run" command: -p 8000:8000 before the image name and --alternator-port=8000 --experimental 1 at the end. The "alternator-port" option specifies on which port Scylla will listen for the (unencrypted) DynamoDB API, and "--experimental 1" is required to enable the experimental LWT feature which Alternator uses. For example, docker run --name scylla -d -p 8000:8000 scylladb/scylla-nightly:latest --alternator-port=8000 --experimental 1

Testing Scylla's DynamoDB API support:

Running AWS Tic Tac Toe demo app to test the cluster:

Follow the instructions on the AWS github page
Enjoy your tic-tac-toe game :-)

Setting up the python environment

Run the following commands on your machine, this will install boto3 python library which also contains drivers for DynamoDB:

sudo pip install --upgrade boto3

Runnning some simple scripts:

The following is a 3 scripts test that creates a table named usertable writes the famous hello world record to it, and then, reads it back.

Put the following create table example script in a python file and run it (changing local host to the address of your docker node if you are using docker):

import boto3
dynamodb = boto3.resource('dynamodb',endpoint_url='http://localhost:8000',
                  region_name='None', aws_access_key_id='None', aws_secret_access_key='None')

dynamodb.create_table(
    AttributeDefinitions=[
    {
        'AttributeName': 'key',
        'AttributeType': 'S'
    },
    ],
    BillingMode='PAY_PER_REQUEST',
    TableName='usertable',
    KeySchema=[
    {
        'AttributeName': 'key',
        'KeyType': 'HASH'
    },
    ])

Put the following write example script in a python file and run it (changing local host to the address of your docker node if you are using docker):

import boto3
dynamodb = boto3.resource('dynamodb',endpoint_url='http://localhost:8000',
                  region_name='None', aws_access_key_id='None', aws_secret_access_key='None')

dynamodb.batch_write_item(RequestItems={
    'usertable': [
        {
             'PutRequest': {
                 'Item': {
                     'key': 'test', 'x' : {'hello': 'world'}
                 }
             },
        }
    ]
})

Put the following read example script in a python file and run it (changing local host to the address of your docker node if you are using docker):

import boto3
dynamodb = boto3.resource('dynamodb',endpoint_url='http://localhost:8000',
                  region_name='None', aws_access_key_id='None', aws_secret_access_key='None')

print(dynamodb.batch_get_item(RequestItems={
    'usertable' : { 'Keys': [{ 'key': 'test' }] }
}))

You should see the record you inserted in step 2 along with some http info printed to screen.

3.5 KiB Raw Blame History