Esper is a tool for exploratory analysis of large video collections.
First, install Docker.
If you have a GPU and are running on Linux:
- Install nvidia-docker.
pip install nvidia-docker-compose
- For any command below that uses
docker-compose
, usenvidia-docker-compose
instead.
If you do not have a GPU or are not running Linux: pip install docker-compose
export MYSQL_PASSWORD=<pick a password, save it to your shell .rc>
alias dc=docker-compose
dc build
dc up -d nginx
dc exec esper ./scripts/setup.sh
Then visit http://yourserver.com
.
The default Esper build comes with a local MySQL database, saved to mysql-db
inside the Esper repository. It is exposed on the default port (3306) and comes with a root user whose password is what you specified in MYSQL_PASSWORD
. Connect to the database with:
mysql -h <your server> -u root -p${MYSQL_PASSWORD} esper
Note: that the root password will be set for good after the first time you run dc up -d nginx
, so you need to either reset the database or run the ALTER PASSWORD
SQL command to change the root password again.
To use the Google Cloud SQL database, first install git-crypt. Get the secret esper.key
from Will and inside the repository run:
git-crypt unlock /path/to/esper.key
Then in docker-compose.yml
under the esper
service, uncomment db-cloud
under depends_on
. Re-run dc down && dc up -d nginx
.
If you want to continue using your local MySQL database but just pull all the data from the cloud, then go into the esper
container and run:
./scripts/load-cloud-db.sh
If you want to use the cloud database as the actual backend for your Django server, then
go to docker-compose.yml
and modify the appropriate environment
settings. Re-run dc down && dc up -d nginx
.
If you're behind a proxy (e.g. the CMU PDL cluster), configure the Docker proxy. Make sure https_proxy
is set in your environment as well.
Use docker-compose
for any network operations like pulling or pushing (nvidia-docker-compose
doesn't properly use a proxy yet). Make sure http_proxy
is NOT set when you do dc up -d nginx
.
You can then use an SSH tunnel to access the webserver from your local machine:
ssh -L 8080:127.0.0.1:80 <your_server>
Then go to http://localhost:8080 in your browser.
To add videos to the database, add them somewhere in the esper
directory (the directory containing manage.py
) and create a file paths
that contains a newline-separated list of relative paths to your videos. Open a shell in the Docker container by running docker-compose exec esper bash
and then run:
python manage.py ingest paths
python manage.py face_detect paths
python manage.py face_cluster paths
Ask Will about getting permissions on the Esper project in Google Cloud. Then, install the Google Cloud SDK. After that, run:
gcloud auth login
gcloud config set project visualdb-1046
gcloud auth application-default login
This sets up your machine for accessing any of the Google Cloud services. Then, download the Google Cloud proxy tool and run:
./cloud_sql_proxy -instances=visualdb-1046:us-central1:esper=tcp:3306
Then download the Esper workbook with:
gsutil cp gs://esper/Esper.twb .
Open up Tableau (download), do File -> Open and open the Esper.twb
file. Replace the prompted user name with your own SQL user and click Sign in.
To use your own MySQL database:
- Click Data Source in the bottom left.
- Click the dropdown arrow in box labeled 127.0.0.1 in the top left underneath Connections.
- Select Edit connection....
- Change the server to wherever your local instance is located.
- Change the username to
root
. - Change the password to the value of your
$MYSQL_PASSWORD
. - Click Sign in.
- Click Update now in the middle-bottom box.
While editing the SASS or JSX files, use the Webpack watcher:
./scripts/build-frontend.sh
This will automatically rebuild all the frontend files into assets/bundles
when you change a relevant file.