To use Cordial, you’ll need an Amazon Web Services account and a computer with Docker. These instructions will walk you through setting both of these up and testing that Cordial is setup correctly.
We run Cordial in a Docker container to make setup easier. On Ubuntu, you’ll be able to work inside of the Docker container with an IDE and other visualization tools, without setting them up on your computer. When you use the run script, your work in
scratch will be saved even if you close the container, because we are using Docker volumes. You can also pass files back and forth between the container and your computer while it’s running by putting them in the
shared directory in
Getting your Amazon Web Service credentials¶
For Cordial to speak we use Amazon Polly, which requires an Amazon Web Services account. At our current usage, using Amazon Polly is free up to a certain level), but you will need a credit card to create an account.
- Create an Amazon Web Services account.
- Once you sign in, in the top right of the page, click your account name (mine says “Audrow”), then in the drop-down menu click “My Security Credentials,” then click “Create New Access Key.”
- Record your access key and keep it somewhere safe. You can do this by downloading this or just viewing it and copy-pasting it to somewhere for later reference.
It is best practice to create separate accounts with less access than your root account and use those access keys, see Amazon’s security best practices.
Running Cordial in a Docker Container¶
curl -fsSL https://get.docker.com -o get-docker.sh sh get-docker.sh
Set Docker to run without
sudo groupadd docker sudo gpasswd -a $USER docker newgrp docker
Test that Docker is installed correctly and works without
docker run hello-world
sudo curl -L "https://github.com/docker/compose/releases/download/1.25.3/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose sudo chmod +x /usr/local/bin/docker-compose
Check that Docker-compose is installed correctly:
Run Cordial’s Docker container. The first time it will take a while, say 10 minutes, depending on your computer and internet speed:
git clone https://github.com/robotpt/cordial bash cordial/docker/run.sh
You can pass arguments to the run script to change how the program is run. If you do
bash cordial/docker/run.sh terminal, the Docker container will run in your current terminal. This is possibly the only way to run Cordial on a Windows or Mac computer without using a virtual machine.
Once in the Docker container, configure your AWS credentials by typing
aws configurein the terminal that pops up. You will be prompted to enter the following:
AWS Access Key IDand
AWS Secret Access Key, enter the corresponding credentials associated with your AWS account.
Default region name, enter the code the region code that you’d like to use. In Los Angeles, we typically use
us-west-1. You can find a full list of region names here.
Default output format, enter
Test that everything is setup correctly by running an example in the Docker container, for example:
roslaunch cordial_manager example_say_and_ask_on_gui.launch
You can then open a web-browser and go to
localhost:8080for the face and
localhost:8081for the GUI. Once these are open, an interaction should begin. You should see the face moving, see the text and some options on the GUI, and hear the voice speaking.
- If nothing happens, check the terminal where you ran the above command. It is quite likely that something is wrong with the AWS credentials. Go back to the previous step.
- If the face moves and GUI displays but you hear no voice, it’s possible Docker can’t find your sound card or that some other program is occupying your sound card. Try closing anything that might play sound (such as a Google Meet call) and retry. You might also see if you can play any sounds from the Docker container, by running, for example,