This is the sample application codebase for the Redis University course RU102PY, Redis for Python Developers.
And this fork is my particular twist to make it work just using docker
and docker-compose
. So, if you have them
installed, you are all set to go! Just follow these steps:
- Clone the repository.
- If you want to run the app just type in your terminal
docker-compose up app
. Now you can go to http://127.0.0.1:8081 and see the app working. - If you want to run the tests,
docker-compose up test
And that's it! The good news is that you can work on your favourite IDE and still keep your changes once you stop the containers, because the sources are shared through a volume.
Note: You can still can run the project as in the original way, but if you want to do that, make sure you change
the files instance/dev.cfg
and intance/testing.cfg
and set REDIS_HOST = "localhost"
on both files.
If you want to learn more about the project or the original way to run it, just keep reading.
To start and run this application, you will need:
- Python 3.8 (Note: It must be version 3.8)
- Access to a local or remote installation of Redis version 5 or newer
- Your Redis installation should have the RedisTimeSeries module installed. You can find the installation instructions at: https://oss.redislabs.com/redistimeseries/#setup
Note: If you don't have Redis installed but do have Docker and want to get started quickly,
run make timeseries-docker
. This starts a Redis container with RedisTimeSeries installed.
This project automates setting up its Python dependencies with make
.
To get started, run make env
. This command creates a virtual environment
and installs the project and its dependencies into the environment.
Follow the steps in this section if you want to manually set up the project.
Note that the Makefile provides targets (e.g. make all
, make backend_dev
,
and make frontend_dev
) that automate everything you should need to do, so
manually setting up the project is not necessary.
If you want to create a virtualenv manually instead of using make env
, run the
following command from the base directory of the project:
python3.8 -m venv env
Before installing dependencies, activate the virtualenv:
source env/bin/activate
Install the app and its dependencies by running the following command from the base directory of the project:
pip install -e .
This project requires a connection to Redis. The default settings expect Redis to run on localhost at port 6379 without password protection.
This project uses the RedisTimeSeries module. You can either install it manually or run Redis with the module enabled using Docker.
Check the project's web site for installation instructions: https://oss.redislabs.com/redistimeseries/
Note: As mentioned earlier in this document, if you have Docker installed and want to get started quickly, run
make timeseries-docker
, which starts a Docker container running Redis with the
RedisTimeSeries module enabled.
If you use Redis with a username (via the new ACL system in Redis 6) and/or a
password, make sure to set the REDISOLAR_REDIS_USERNAME
and/or
REDISOLAR_REDIS_PASSWORD
environment variables before running project-related
make
commands or manual commands.
You can set these on the command line like so:
$ REDISOLAR_REDIS_USERNAME=your-username make load
However, doing so keeps a record of these variables around in your shell history.
The example project is configured to read environment variables from a .env
file, so if you do need to use environment variables, we recommend adding them
to this file.
Note: The .env
file is ignored by git because we added it to the
.gitignore
file. If you use a .env
file, you should avoid adding it to git,
so your credentials don't end up in git's history.
Finally, credential management is a big topic. This is just a demo project -- make sure you follow your company's guidelines for credentials management.
Important note: If you are not using Redis on localhost at port 6379, you need to update the following files:
redisolar/instance/dev.cfg
redisolar/instance/testing.cfg
In the referenced files, change the values of REDIS_HOST
and REDIS_PORT
to
the correct values for your Redis instance.
This project prefixes all keys with a string. By default, the dev server and sample data loader use the prefix "ru102py-app:", while the test suite uses "ru102py-test:".
When you run the tests, they add keys to the same Redis database that the running Flask application uses, but with the prefix "test:". Then when the tests finish, the test runner deletes all the keys prefixed with "test:".
You can change the prefix used for keys by changing the REDIS_KEY_PREFIX
option in the following files:
redisolar/instance/dev.cfg
redisolar/instance/testing.cfg
Before the example app will do anything interesting, it needs data.
You can use the command make load
to load solar sites and generate example
readings. make load
loads data into the Redis instance that you configured in
redisolar/instance/dev.cfg
, using the REDIS_HOST
and REDIS_PORT
defined there.
Note: Read through the "Redis" section in this README to make sure you've properly configured the sample application to connect to Redis before you load sample data.
Run the development server with make dev
.
Note: By default, the server runs with geographic features disabled. To run
with geo features enabled, set the option USE_GEO_SITE_API
in
redisolar/instance/dev.cfg
to True
.
After running make dev
access https://localhost:8081 to see the app.
Don't see any data?
The first time you run make dev
, you may see a map with nothing on it. In
order to see sites on the map, you'll need to do two things:
- Follow the instructions in this README to load data
- Complete Challenge #1 in the course
If you need to override command-line flags when running Flask, you can use the flask
command to run the dev server manually.
To do, first activate the project's virtual environment:
$ source env/bin/activate
Then run the flask
command:
$ FLASK_APP=redisolar flask run --port=8001
You can run make test
to run the unit tests. Doing so will build
a virtualenv automatically if you have not already done so.
You can run individual tests by calling pytest
manually. To do, first activate the project's virtual environment:
$ source env/bin/activate
Then run pytest
with whatever options you want. For example, here is how you
run a specific test:
$ pytest -k test_set_get
This project requires Python 3.8. See the "Prerequisites" section of this README. You will need to install Python 3.8 on your machine, or else use our "lab" Docker image -- see the "Setup" tab in the course for more details.
You might see an error like this (or many of them) when you try to run the tests:
ERROR tests/scripts/test_update_if_lowest.py::test_update_if_lowest_unchanged - redis.exceptions.ConnectionError: Error 61 connecting to localhost:6379. Connection refused.
The error is telling you that Redis is not running on port 6379. Make sure you've started Redis -- exactly how to do so depends on your operation system and the way you installed Redis. For example, if you installed via Homebrew on a Mac, the command is:
brew services start redis
Your Redis instance requires a username and/or password to connect. First, find out what those are. Then follow the "Username and password protection" section of this README to configure the project to connect with those credentials.
Your Redis instance does not have the RedisTimeSeries module installed. See the section "RedisTimeSeries" in this README for instructions.
Chat with our teaching assistants on the Redis University Discord Server.
This project is released under the MIT license. See LICENSE for the full text.