You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: docs/src/setup.md
+33-41
Original file line number
Diff line number
Diff line change
@@ -55,68 +55,60 @@ cp -n .env.example .env
55
55
???+ danger
56
56
If you do any commits to the repo, _please make sure `.env` is properly gitignored!_ (`.env.example` does not need to be gitignored, only `.env`.) `.env` contains sensitive information.
57
57
58
-
5. The previous step created a file called `.env` (pronounced "dot env"). This file will contain our HOBOlink credentials and Twitter/X credentials.
58
+
5. The previous step created a file called `.env` (pronounced "dot env"). This file will contain things like HOBOlink credentials and Twitter/X credentials.
59
59
60
-
Please update `.env` (**_NOT_**`.env.example`) to contain the correct credentials by replacing each `replace_me`. The Twitter/X credentials are optional.
60
+
Please update `.env` (**_NOT_**`.env.example`) to contain the correct credentials by replacing each `replace_me`.
61
61
62
-
If you do not have HOBOlink credentials, please turn on demo mode by setting `FLASK_ENV=demo`.
62
+
If you do not have HOBOlink credentials, please turn on demo mode by setting `USE_MOCK_DATA=true`.
63
+
64
+
**(Optional)** If you'd like, create a Mapbox access token and add it to your `.env`: https://www.mapbox.com/ If you don't do this, the map will not fully render.
65
+
66
+
**(Very optional)** If you'd like, connect to Sentry via the `SENTRY_DSN` and `SENTRY_ENVIRONMENT` env vars: https://sentry.io/
67
+
68
+
**(Very optional)** You can also set up `https` and run that way. Create a certfile and key via the command `./run ssl-cert`, and add `CERTFILE=server.crt`, `KEYFILE=server.key`, and `PORT=443` to your `.env`. However this will require some additional finagling as your browser will not by default trust self-signed certs, so it's not recommended for most users.
69
+
70
+
**(Very optional)** You can also set up Twitter/X credentials and send tweets. However, right now we do not use Twitter/X; this functionality is effectively deprecated.
63
71
64
72
## Run the Website Locally
65
73
66
74
After you get everything set up, you should run the website at least once.
67
75
68
-
1. Although not strictly required for running the website (as we will be using Docker Compose), it is recommended you install all the project dependencies into a virtual environment.
76
+
1. Although not strictly required for running the website (as we will be using Docker Compose), it is recommended you install all the project dependencies into a virtual environment, and also enable `pre-commit` (which does checks of your code before you commit changes).
69
77
70
78
To do this, run the following:
71
79
72
-
```
73
-
uv pip sync requirements.txt
74
-
```
75
-
76
-
77
80
=== "Windows (CMD)"
78
81
```shell
79
-
run_windows_dev
82
+
uv venv .venv
83
+
.\.venv\Scripts\activate.bat
84
+
uv pip sync requirements.txt
85
+
pre-commit install
80
86
```
81
87
82
88
=== "OSX (Bash)"
83
89
```shell
84
-
sh run_unix_dev.sh
90
+
uv venv .venv
91
+
source .venv/bin/activate
92
+
uv pip sync requirements.txt
93
+
pre-commit install
85
94
```
86
95
87
-
???+ note
88
-
The script being run is doing the following, in order:
89
-
90
-
1. Set up a "virtual environment" (basically an isolated folder inside your project directory that we install the Python packages into),
91
-
2. install the packages inside of `requirements/dev.txt`; this can take a while during your first time.
92
-
3. Set up some environment variables that Flask needs.
93
-
4. Prompts the user to set some options for the deployment. (See step 2 below.)
94
-
5. Set up the Postgres database and update it with data.
95
-
6. Run the actual website.
96
+
2. Build the Docker images required to run the site:
96
97
97
-
???+ tip
98
-
If you are receiving any errors related to the Postgres database and you are certain that Postgres is running on your computer, you can modify the `POSTGRES_USER` and `POSTGRES_PASSWORD` environment variables to connect to your local Postgres instance properly.
99
-
100
-
You can also save these Postgres environment variables inside of your `.env` file, but **do not** save your system password (the password you use to login to your computer) in a plain text file. If you need to save a `POSTGRES_PASSWORD` in `.env`, make sure it's a unique password, e.g. an admin user `POSTGRES_USER=flagging` and a password you randomly generated for that user `POSTGRES_PASSWORD=my_random_password_here`.
101
-
102
-
2. You will be prompted asking if you want to run the website with mock data. The `USE_MOCK_DATA` variable is a way to run the website with dummy data without accessing the credentials. It is useful for anyone who wants to run a demo of the website regardless of their affiliation with the CRWA or this project. It has also been useful for development purposes in the past for us.
103
-
104
-
3. Now just wait for the database to start filling in and for the website to eventually run.
98
+
```shell
99
+
docker compose build
100
+
```
105
101
106
-
???+ success
107
-
You should be good if you eventually see something like the following in your terminal:
* Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
114
-
* Restarting with stat
115
-
```
104
+
```shell
105
+
docker compose up
106
+
```
116
107
117
-
???+ error
118
-
If you get an error that says something like "`Microsoft Visual C++ 14.0 or greater is required.`," you need to follow the link provided by the error message, download and install it, then reboot your computer.
108
+
4. If this is your first time running the website, you will need to populate the database by running the batch job that retrieves data and runs the model. To do this, **in a separate terminal** (while the other terminal is still running), run the following command:
119
109
120
-
4. Point your browser of choice to the URL shown in the terminal output. If everything worked out, the website should be running on your local computer!
110
+
```shell
111
+
docker compose exec web flask update-db
112
+
```
121
113
122
-
114
+
Now visit the website at `http://localhost/` (note it's http, not https). And you should be all set!
0 commit comments