From 3b91727711541063573e60224896a5f3f76412e3 Mon Sep 17 00:00:00 2001 From: BeritJanssen Date: Mon, 9 Oct 2023 17:04:32 +0200 Subject: [PATCH 1/4] close #567, close #566: add information on code editor and git --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index 0b4019ab6..41bb5dd25 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,9 @@ This application provides an easy way to implement and run online listening expe - We are also happy if you file a feature request in our [issues list](https://github.com/Amsterdam-Music-Lab/aml-experiments/issues), or if you fork this repository to add your own code. +## Before installation +We recommend downloading a code editor, for instance [Visual Studio Code](https://code.visualstudio.com/), and to use [git](https://git-scm.com/) to copy this repository to your machine, as this makes it easier to keep your local copy up to date. + ## Installation with Docker The easiest way to run the application locally is through Docker. From ec0ef959677ed786125046ac6ddfa74a21e35a8f Mon Sep 17 00:00:00 2001 From: BeritJanssen Date: Tue, 10 Oct 2023 07:15:52 +0200 Subject: [PATCH 2/4] close #569, close #573 update instructions for .env file --- .env.dist | 41 +++++++++++++++++++++++------------------ README.md | 27 +++++++-------------------- 2 files changed, 30 insertions(+), 38 deletions(-) diff --git a/.env.dist b/.env.dist index 4ee5ed69d..50f5ea73c 100644 --- a/.env.dist +++ b/.env.dist @@ -1,18 +1,23 @@ -SQL_DATABASE= -SQL_USER= -SQL_PASSWORD= -SQL_HOST= -AML_DEBUG=true -DJANGO_SETTINGS_MODULE=aml.development_settings -AML_LOCATION_PROVIDER=http://ip2country:8854 -REACT_APP_API_ROOT=http://localhost:8000 -REACT_APP_EXPERIMENT_SLUG= -REACT_APP_AML_HOME=https://www.amsterdammusiclab.nl -REACT_APP_LOGO_URL= -REACT_APP_HTML_PAGE_TITLE=Amsterdam Music Lab Experiment -REACT_APP_HTML_FAVICON=/favicon.ico -REACT_APP_HTML_OG_DESCRIPTION=Listening experiments from the Amsterdam Music Lab. Test your musical knowledge and skills in engaging citizen-science experiments. -REACT_APP_HTML_OG_IMAGE= -REACT_APP_HTML_OG_TITLE=Amsterdam Music Lab Experiment -REACT_APP_HTML_OG_URL= -REACT_APP_HTML_BODY_CLASS= \ No newline at end of file +SQL_DATABASE=muscle # you can change this to an arbitrary value before first startup +SQL_USER=muscle # you can change this to an arbitrary value before first startup +SQL_PASSWORD=musclepassword # change this to a safe password when running in production +SQL_HOST=db # name of database container, don't change +SQL_PORT=5432 # port where to reach the database, don't change + +AML_SECRET_KEY=supersecret # change this to a safe password when running in production +AML_DEBUG=true # change this to false when running in production +DJANGO_SETTINGS_MODULE=aml.development_settings # change this to aml.production_settings when running in production +AML_LOCATION_PROVIDER=http://ip2country:5000/{} # address of the ip2country container, don't change +ALLOWED_HOSTS=localhost # needs to be changed when running in production + +REACT_APP_API_ROOT=http://localhost:8000 # address of the server, don't change +REACT_APP_EXPERIMENT_SLUG=gmsi # experiment slug that the frontend redirects to +REACT_APP_AML_HOME=https://www.amsterdammusiclab.nl # website you will be redirected to if you do not agree with an informed consent form +REACT_APP_LOGO_URL= # optional: link to logo +REACT_APP_HTML_PAGE_TITLE=Amsterdam Music Lab Experiment # optional: information for web crawlers +REACT_APP_HTML_FAVICON=/favicon.ico # optional: which image to use as favicon +REACT_APP_HTML_OG_DESCRIPTION=Listening experiments from the Amsterdam Music Lab. Test your musical knowledge and skills in engaging citizen-science experiments. # optional: information for web crawlers +REACT_APP_HTML_OG_IMAGE= # optional: information for web crawlers +REACT_APP_HTML_OG_TITLE=Amsterdam Music Lab Experiment # optional: information for web crawlers +REACT_APP_HTML_OG_URL= # optional: information for web crawlers +REACT_APP_HTML_BODY_CLASS= # optional: assign a css class to the tag in index.html, for custom styling \ No newline at end of file diff --git a/README.md b/README.md index 41bb5dd25..32edf868f 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ This application provides an easy way to implement and run online listening expe We recommend downloading a code editor, for instance [Visual Studio Code](https://code.visualstudio.com/), and to use [git](https://git-scm.com/) to copy this repository to your machine, as this makes it easier to keep your local copy up to date. ## Installation with Docker -The easiest way to run the application locally is through Docker. +The easiest way to run the application locally is through Docker. Docker is an application which runs a network of virtual machines ("containers") and is therefore (mostly) platform independent. ### Mac OS X or Windows 10 Install [Docker Desktop](https://docs.docker.com/desktop/). @@ -26,24 +26,9 @@ Install [Docker Desktop](https://docs.docker.com/desktop/). As of April 2022, [Docker Desktop for Linux](https://docs.docker.com/desktop/linux/) is still in Beta and have not been tested by us. ## Development build -Make a file called .env next in this directory, with the following settings. Change database name and user and passwords as appropriate. The only setting that you'll have to set later is the slug, which depends on the slug (short name) of an existing experiment in your database. -``` -SQL_DATABASE=aml -SQL_USER=aml -SQL_PASSWORD=supersecretpassword -SQL_HOST=db -SQL_PORT=5432 - -AML_SECRET_KEY=secretdjangopassword -AML_LOCATION_PROVIDER=http://ip2country:5000/{} -AML_DEBUG=True -DJANGO_SETTINGS_MODULE=aml.development_settings - -REACT_APP_API_ROOT=http://localhost:8000 -REACT_APP_EXPERIMENT_SLUG=your_slug -REACT_APP_AML_HOME=https://www.amsterdammusiclab.nl -``` -Then, open a console and run +Make a copy of the file .env.dist (in the same directory as this README) and rename it to .env. This file contains variables used by Docker to start up a container network serving MUSCLE. + +Then, open a terminal and run `docker-compose up` (add `sudo` on Linux). This command makes use of the `docker-compose.yaml`, which defines four containers: - a PostgreSQL container, for storing experiment/user/playlist data, saved on the host machine in the Docker user data, represented in the volume `db_data`. Data added to the database will persist if the container is shut down. @@ -51,9 +36,11 @@ This command makes use of the `docker-compose.yaml`, which defines four containe - a container of the server, defined in DockerfileDevelop in `backend`. The Dockerfile defines the Python version and installs development dependencies. The startup command runs migrations and then starts up a Django development server. - a container of the client, defined in DockerfileDevelop in `frontend`. The Dockerfile defines the node version and installs node modules. The startup command kicks off a React development server. +Once you see all containers have started up, open your browser and navigate to [localhost:3000](http://localhost:3000). You should now be able to see the first screen of the Goldsmiths Musical Sophistication Index questionnaire. + Since the `docker-compose.yaml` defines bind mounts for `backend` and `frontend`, any changes to the files on the host are immediately reflected in the containers, which means code watching works and hot reload works in the same way as with a native node or Django server. -To stop the containers, press `ctrl-c` or (in another console) run +To stop the containers, press `ctrl-c` or (in another terminal) run `docker-compose down`. ## Production build From 2fb7e92f2b2c5b04a467563a5c91b39691f89290 Mon Sep 17 00:00:00 2001 From: BeritJanssen Date: Tue, 10 Oct 2023 07:20:17 +0200 Subject: [PATCH 3/4] close #571: start Docker in README --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 32edf868f..c9c99220a 100644 --- a/README.md +++ b/README.md @@ -28,11 +28,11 @@ As of April 2022, [Docker Desktop for Linux](https://docs.docker.com/desktop/lin ## Development build Make a copy of the file .env.dist (in the same directory as this README) and rename it to .env. This file contains variables used by Docker to start up a container network serving MUSCLE. -Then, open a terminal and run +Start Docker (the app icon is a whale carrying containers). Then, open a terminal and run `docker-compose up` (add `sudo` on Linux). -This command makes use of the `docker-compose.yaml`, which defines four containers: +This command starts up the containers defined in `docker-compose.yaml`: - a PostgreSQL container, for storing experiment/user/playlist data, saved on the host machine in the Docker user data, represented in the volume `db_data`. Data added to the database will persist if the container is shut down. -- a ip2country container, which provides country codes for ip addresses. This container is mainly interesting for running tests during development. +- a ip2country container, which provides country codes for ip addresses, used for demographic information of users. - a container of the server, defined in DockerfileDevelop in `backend`. The Dockerfile defines the Python version and installs development dependencies. The startup command runs migrations and then starts up a Django development server. - a container of the client, defined in DockerfileDevelop in `frontend`. The Dockerfile defines the node version and installs node modules. The startup command kicks off a React development server. From 47c5b06538f17750b8ec4522d23686e3ed3fec2c Mon Sep 17 00:00:00 2001 From: BeritJanssen Date: Tue, 10 Oct 2023 07:24:38 +0200 Subject: [PATCH 4/4] add info for .env file in production --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index c9c99220a..70703fc3e 100644 --- a/README.md +++ b/README.md @@ -44,4 +44,4 @@ To stop the containers, press `ctrl-c` or (in another terminal) run `docker-compose down`. ## Production build -A production build should define its own `docker-compose.yaml`, making use of the `Dockerfile` of the `backend` and `frontend` environments. Instead of mounting the entire backend and frontend directory and using the development servers, the backend should serve with gunicorn, and the frontend should use a build script to compile static html, css and JavaScript. +A production build should define its own `docker-compose.yaml`, making use of the `Dockerfile` of the `backend` and `frontend` environments. It should also define a custom .env file, with safe passwords for the SQL database and the Python backend. Instead of mounting the entire backend and frontend directory and using the development servers, the backend should serve with gunicorn, and the frontend should use a build script to compile static html, css and JavaScript.