|
1 | 1 | # tbpweb |
2 | | -TBP CA-A website rework, build in Django |
| 2 | +TBP CA-A website, built in Django |
3 | 3 |
|
4 | | -## Setup |
| 4 | +## Prerequisites |
5 | 5 |
|
6 | | -**Vagrant** will automatically setup a virtual machine with the correct |
7 | | -setup for developing `hknweb`. |
| 6 | +For a more detailed explaination and instruction on what to install, see the [Setup's Prerequisites section](https://github.com/TBP-IT/tbpweb/wiki/Setup#prerequisites) |
8 | 7 |
|
9 | | -Install [Vagrant](https://www.vagrantup.com/) and [VirtualBox](https://www.virtualbox.org/wiki/Downloads) |
10 | | -It is okay to install the latest of both (and mostly recommended)! Otherwise, consult with another Officer who has the setup working and first try to match the VirtualBox version and then the Vagrant version. |
| 8 | +In summary, you need the following installed: |
| 9 | +* `git` |
| 10 | +* Any `sh` shell (e.g. `bash`, `zsh`, etc.) / `Git Bash` on Windows |
| 11 | +* Miniconda (or Anaconda) |
| 12 | +* Ruby (OCF uses 2.7.7, but we can use 3.1.X) (Windows should use `Ruby+Devkit`) |
| 13 | + * Install "Compass": `gem install compass -v 1.0.3` |
11 | 14 |
|
12 | | -*In one point in time, there have been some issues in the past with other versions of Virtual Box in terms of compatibility of Vagrant. |
13 | | -You can find those here [VirtualBox Old 6.0 Builds](https://www.virtualbox.org/wiki/Download_Old_Builds_6_0), and at the time, Virtual Box 6.0.14 was recommended* |
| 15 | +## Setup and Development |
14 | 16 |
|
15 | | -Fork the tbpweb repository and clone your fork to your local machine |
| 17 | +For a more detailed explaination and breakdown, see the [Setup Wiki](https://github.com/TBP-IT/tbpweb/wiki/Setup) |
16 | 18 |
|
17 | | -Open terminal, and cd into the cloned directory (if on Windows, be sure to run Command Prompt instead, as administrator). Check to make sure there is a Vagrantfile in the directory. If on Windows, also run VirtualBox as admin. Then, from the cloned directory in terminal, type |
| 19 | +Fork the tbpweb repository and clone your fork to your local machine |
18 | 20 |
|
19 | | -```sh |
20 | | -$ vagrant up |
21 | | -``` |
22 | | - |
23 | | -which will download and boot a Linux virtual machine, then run setup. |
24 | | - |
25 | | -To access the environment, run |
26 | | - |
27 | | -```sh |
28 | | -$ vagrant ssh |
29 | | -``` |
30 | | - |
31 | | -which will `ssh` your terminal into the virtual machine. |
32 | | - |
33 | | -See [Development](#development) for how to run the Django web server. |
34 | | - |
35 | | -From here, run |
36 | | - |
37 | | -```sh |
38 | | -$ cd tbpweb |
39 | | -``` |
40 | | - |
41 | | -Developing on `tbpweb` requires a virtual environment so that every developer has the exact same development environment i.e. any errors that a developer has is not due to difference in configuration. We will be using Python's built-on [`venv`](https://docs.python.org/3/library/venv.html) to make our virtual environment. This command creates our virtual environment. |
42 | | - |
43 | | -```sh |
44 | | -$ make venv |
45 | | -``` |
46 | | - |
47 | | -Next, we need to have our current terminal/shell use the virtual environment we just created. We do this through: |
48 | | - |
49 | | -```sh |
50 | | -$ source .venv/bin/activate |
51 | | -``` |
52 | | - |
53 | | -To install all dependencies (including django), run |
54 | | - |
55 | | -```sh |
56 | | -$ make install |
57 | | -``` |
58 | | -There may be warnings that installation of some packages failed, but as long as you can run the command below successfully you are good to go. |
| 21 | +All commands must be ran on a `sh` shell |
59 | 22 |
|
60 | | -If you make any Django changes (to the database models, for instance) you will have to create and migrate migrations. You can do so with the command below. If there were changes to database models made by other developers and you pulled those changes, you just have to run make migrate. |
| 23 | +In summary, the commands you will use are (in general this order): |
61 | 24 | ```sh |
62 | | -$ make migrations |
63 | | -$ make migrate |
| 25 | +$ cd tbpweb # enter our main directory |
| 26 | +$ conda env create -f config/tbpweb-dev.yml # create our Conda Environment and install dependencies |
| 27 | +$ conda activate tbpweb-dev # enter our Conda Environment |
| 28 | +$ python manage.py makemigrations # Create migrations files |
| 29 | +$ python manage.py migrate # apply all database changes |
| 30 | +$ python manage.py runserver 0.0.0.0:3000 # start local web server |
| 31 | +$ conda deactivate # Exit the Conda Environment |
64 | 32 | ``` |
65 | 33 |
|
66 | | -If you would like to access the admin interface, create a superuser using the command |
67 | | -```sh |
68 | | -$ make superuser |
69 | | -``` |
| 34 | +You may choose to remove the development environment by running: `conda env remove --name tbpweb-dev` |
70 | 35 |
|
71 | | -Finally, to run the web instance, simply run the command |
| 36 | +### Development |
72 | 37 |
|
| 38 | +To run the Django development server (which runs a web server locally), run |
73 | 39 | ```sh |
74 | | -$ make run |
| 40 | +$ python manage.py runserver 0.0.0.0:3000 |
75 | 41 | ``` |
76 | | -This will start the development server at http://0.0.0.0:3000/. If you go into your web browser and access localhost:3000, you should be able to see the site now! |
77 | | - |
78 | | -To access the admin site, access http://0.0.0.0:3000/admin. Use the credentials you created for your superuser to login. |
79 | | - |
80 | | -To exit out of the pipenv shell, run |
| 42 | +which will make the web site available at `http://localhost:3000`. |
81 | 43 |
|
| 44 | +If you would like to access the admin interface in the local web server, run |
82 | 45 | ```sh |
83 | | -$ exit |
| 46 | +$ python manage.py createsuperuser |
84 | 47 | ``` |
85 | | -The same command can be used to exit out of the virtual machine ssh connection. |
86 | | - |
87 | | -To turn off the virtual machine, run |
88 | 48 |
|
89 | | -```sh |
90 | | -$ vagrant halt |
91 | | -``` |
| 49 | +You will be prompted for some login info, after which you should be able to access the admin interface with your super user credentials at `http://localhost:3000/admin`. |
92 | 50 |
|
93 | | -which will attempt to safely shutdown the virtual machine, or kill it otherwise. |
| 51 | +If there are development conflicts between Operating System, a solution that works on Linux takes precedence (as the destination OS on Berkeley's OCF)! Unix developers should also try to make their code Windows-friendly for the Window developers. |
94 | 52 |
|
95 | 53 | ## Deploy |
96 | 54 |
|
97 | 55 | Make sure all changes to be pushed are in `tbpweb`'s `master` branch |
98 | 56 |
|
99 | | -Deploy by running `fab --prompt-for-login-password deploy` in the Vagrant VM and enter the TBP OCF credentials |
| 57 | +Deploy by running `fab --prompt-for-login-password deploy` in the Conda Environment and enter the TBP OCF password |
100 | 58 |
|
101 | | -This script is adapted from HKN's fabfile, so you can find other commands (including rollback) here: https://github.com/compserv/hknweb/wiki/Deployment |
| 59 | +Other fabfile commands (including rollback) here: https://github.com/TBP-IT/tbpweb/wiki/Deployment |
102 | 60 |
|
103 | 61 | ## Various links to understand some of the code structure and tools |
104 | 62 |
|
|
0 commit comments