Co-Op Documentation

Welcome aboard! I’m sure you’re both excited and a bit nervous, but don’t worry—that’s completely normal. In fact, I’d be concerned if you weren’t! Before long, you’ll be writing a similar document for the next co-op, just as I’m doing for you now.

I’m assuming you’ve reviewed the documents from previous team members. You might find it helpful to follow the order outlined below:

• Co-op First Week Onboarding by Karan
• Using SSH Keys to Connect to GitLab by Archie
• Using SSH with Visual Studio Code by Nick
• Software Development Guidelines by Drew
• Get To Know Git by Priya
• Indentation and Styling Guide by Karan
• Django Development Tips by Archie

Note: Your VM is most likely ready, but you’ll need to send Drew your SSH public key (the one ending in .pub in your .ssh directory) so you can connect to it. Also, you’re not required to use Visual Studio Code—other team members have successfully used Neovim and Vim as well.

On your first day, try to complete the first 3 documents. This will set you up nicely for the following week. However, don’t worry if you don’t finish everything—sometimes things don’t go as planned, and that’s okay!

Troubleshooting

Unable to Connect to the VM

1. The first document in the list, written by Karan, walks you through setting up your laptop and VM. However, if you encounter issues connecting to your VM from the terminal, check if the following WSL components are installed:

   • Ubuntu 18.04 LTS
   • WSL Version 1

   For some reason, WSL Version 2 didn’t work well for me, nor did newer versions of Ubuntu. Downgrading WSL from Version 2 is straightforward (a quick Google search should help), and you can select your Ubuntu version from the Microsoft Store.

2. If you still can’t connect to your VM, ensure you are connected to the VPN using the 2 - Employee Dept Network group in the AnyConnect client.

ZooDB

To learn more about ZooDB’s background, refer to this post on the ARCsoft website. It explains things better than I can!

Technology

ZooDB consists of multiple components, and its architecture varies depending on the environment—development or production. The diagram below outlines the general structure of ZooDB in a production environment:

flowchart LR
 ZooDB --> Django
 Django <--> db[(PostgreSQL)]
 Django --> Keycloak
 NGINX --> Django
 Keycloak --> db

In a development environment, NGINX is not used since static files are served locally, and authentication with Keycloak is disabled.

Basics

After cloning the ZooDB repository, you’ll notice the large README. Don’t worry—setting up your local environment is simpler than it seems. Just follow these steps:

1. Create and activate your Python virtual environment:

     make dev-setup && . venv/bin/activate
   

2. Make any necessary migrations for Django:

     zoosite-main/manage.py migrate
   

3. Run the server:

     zoosite-main/manage.py runserver
   

4. Access the server: depending on your VM’s full hostname, navigate to this URL: http://<vm-full-hostname>:8001/zooapp/. You may encounter some issues, such as CSS not rendering or authentication problems. These are likely due to two variables in settings.py:

5. DEBUG is set to true by default, which prevents debug screens from appearing. Set DEBUG = false to enable them and get useful error information.

6. SESSION_COOKIE_SECURE is set to true by default, which enforces HTTPS for cookies. Change SESSION_COOKIE_SECURE = False to avoid authentication issues in the development environment.

Optionally, you can also set SESSION_COOKIE_AGE to a higher value than 3600 seconds, as this variable represents the maxmium session duration in seconds-in this case you are logged out after an hour.

Note: Do not commit these changes to Git. If you accidentally do, just revert them to the default values!

Additionally, rather than changing these settings individually each and every time, you can create a local_settings.py file in the zooapp directory. This file can override the default settings in settings.py and is ignored by Git. Here’s an example of what local_settings.py might look like:

DEBUG = false
SESSION_COOKIE_SECURE = False
SESSION_COOKIE_AGE = 86400 # 60 days

Testing

ZooDB, like other projects, includes tests. It’s a good habit to run all tests before opening a merge request. The test-all script runs the test harness, as shown in the following diagram:

flowchart TD
 test-all --> sg1
 subgraph sg1[" "]
  Linting --> djLint
  Linting --> djHTML
  Linting --> pylint
  Linting --> bashcheck
 end
 
 test-all --> sg2
 subgraph sg2[" "]
  User-Interface --> Selenium
 end
 
 test-all --> sg3
 subgraph sg3[" "]
  Unit --> Nosetests
 end

Note: The structure of test-all is consistent across most projects, with minor variations. For example, ZooDB is currently the only project with functional UI testing.

To run all tests, run this command from the project’s root directory: tests/test-all

You can also pass optional flags:

• --no-unit: Exclude unit tests
• --no-linting: Exclude linting
• --no-ui: Exclude UI tests
• --pick: Pick or generate a new fixture file from the database

Nice-to-Knows

Flushing the Database

Flushing deletes all data from the app’s database tables while keeping the structure intact. It’s usually done during testing to reset the database to a clean state.

To flush the database, run this command from the project’s root directory:

  zoosite-main/manage.py flush

You can skip the confirmation prompt by adding the --no-input flag, but ensure flushing is the correct action before doing so!

Debugging UI Tests

UI tests can be flaky due to the complexities of their execution environment, often requiring debugging. For more details on ZooDB’s UI testing and the Selenium Grid, check out the uitest script documentation here.

When debugging, it’s usually faster to run a single test case rather than the entire suite, as running all 20+ tests can take several minutes. As mentioned previously, the documentation for uitest includes instructions on running individual test cases.

Gaining Elevated Privileges

To develop new features or fix bugs for ZooDB, you’ll need elevated permissions for certain actions, such as ingesting data or editing admin-only components.

To grant yourself all available permissions, follow these steps:

1. Create a new superuser account:

     python manage.py createsuperuser # Follow the terminal prompts
   

2. Navigate to the admin dashboard at http://<vm-full-hostname>:8001/admin/.

3. Log in with your superuser credentials.

4. Under Site administration > Authentication and Authorization, click Users.

5. Find your username in the table and click on it.

6. Scroll down to the Permissions section.

7. Under Groups, select Owner from the Available groups list.

8. Click the right arrow to move Owner to the Chosen groups list.

9. Scroll to the bottom and click Save.

You should now have all the available permissions when logged in as the superuser!

Future Projects

ZooDB is our first major project and the foundation of our main Django projects. Throughout its development, we have refined our framework knowledge and established internal development standards. Future projects will adhere to these standards and follow a similar architectural structure, making familiarity with ZooDB beneficial for understanding the design of upcoming projects.

Glossary