Skip to content

setup.md

Latest commit

 

History

History
525 lines (343 loc) · 20.5 KB

setup.md

File metadata and controls

525 lines (343 loc) · 20.5 KB

Lab setup

1. Required steps

Important

Some steps have the (UPD) label.

These steps must be completed to get the right setup for this lab, even if you have completed similar steps in the previous lab.

Note

We provide all of the hardest steps in the lab setup so that TAs can help you get the right setup during the lab.

Tasks are more or less easy when you have the right setup.

1.1. (UPD) Find a partner

  1. Find a partner for this lab.
  2. Sit next to them.

Important

You work on tasks independently from your partner.

You and your partner work together when reviewing each other's work.

1.2. Start creating a VM

Note

Skip this step if you can connect to your VM.

Create a subscription to be able to create a VM.

Tip

Subscription approval may take time. Continue with the next steps while you wait — you will finish creating the VM later.

1.3. Set up your fork

1.3.1. Sign in on GitHub

  1. Sign in on GitHub.
  2. Find <your-github-username>.

1.3.2. (UPD) Fork the course instructors' repo

  1. Fork the course instructors' repo.

    The course instructors' repo URL is https://github.com/inno-se-toolkit/se-toolkit-lab-4.

1.3.3. (UPD) Go to your fork

  1. Go to your fork.

    The URL of your fork should look like https://github.com/<your-github-username>/se-toolkit-lab-4.

1.3.4. (UPD) Enable issues

  1. Enable issues.

1.3.5. (UPD) Add a classmate as a collaborator

  1. Add a collaborator — your partner.
  2. Your partner should add you as a collaborator in their repo.

Note

It's OK if your collaborator can't change Settings in your repo.

1.3.6. (UPD) Protect your main branch

Note

Branch protection prevents accidental pushes directly to main. This enforces the PR workflow and ensures all changes are reviewed.

  1. Protect the main branch.

1.4. Set up programs

1.4.1. (UPD) Set up VS Code

  1. (Optional) Read about VS Code.
  2. Set up VS Code.

1.4.2. (UPD) Set up Docker

  1. (Optional) Read about Docker.
  2. Install Docker if it's not installed.
  3. Start Docker.

1.4.3. (UPD) (Windows only) Switch to the Linux shell for the VS Code Terminal

  1. Check the current shell in the VS Code Terminal.
  2. If it's not bash or zsh, switch to the Linux shell for the VS Code Terminal.
  3. Check the current shell again.

1.4.4. Clean up Docker

  1. Clean up Docker.

    Note: Old containers and volumes from a previous lab version may conflict with the updated services. Stop running containers, remove stopped containers, and delete unused volumes so you start with a clean state.

1.4.5. Set up Git

  1. (Optional) Read about Git.
  2. Install Git if it's not installed.
  3. (Optional) Configure Git.

1.5. (UPD) Open in VS Code the software-engineering-toolkit directory

  1. Inside the Desktop directory, create the directory software-engineering-toolkit.

    Skip this step if this directory exists.

  2. Open in VS Code the directory: software-engineering-toolkit.

  3. (Windows only) Reopen the directory in WSL if you didn't do that before.

1.6. Clone your fork

1.6.1. (UPD) Copy your fork URL

  1. Go to your fork.

  2. Copy <your-fork-url>.

    It should look like https://github.com/<your-github-username>/se-toolkit-lab-4.

    See <your-github-username>.

1.6.2. (UPD) Clone your fork

  1. Clone your fork:

    • Replace <repo-url> with <your-fork-url>.
    • Replace <repo-name> with se-toolkit-lab-4.

1.7. (UPD) Open the cloned repo and set up VS Code

Important

Go by the links in the steps below and complete the checks ("You should see ..."). Otherwise, your setup will be broken.

  1. Open in VS Code the directory: se-toolkit-lab-4.
  2. Check the current shell in the VS Code Terminal.
  3. Install the recommended VS Code extensions.
Troubleshooting

The terminal shell is not bash or zsh

Go back to step 1.4.3 and set the default shell.

Recommended extensions did not install

Reload the VS Code window: press Ctrl+Shift+P, type Reload Window, and press Enter.

1.8. Continue creating a VM

Note

Don't overwrite the key if it already exists. You can use the key that you created before for the new VM.

If you can't connect to your VM, complete these steps:

  1. Set up SSH.
  2. Create a VM using the subscription.

1.9. Set up Python

Note

See What is Python.

1.9.1. Install uv

Note

See uv.

  1. Install uv.

1.9.2. (UPD) Set up Python in VS Code

Note

The dependencies have been updated in this project version.

  1. Set up Python in VS Code.

1.10. (UPD) Set up Node.js

  1. Set up Node.js.

    Note: you've already opened the project directory.

1.11. Start the services

Note

See service.

1.11.1. (UPD) Set up the Docker environment

  1. To copy the .env.docker.example file to the .env.docker.secret file,

    run in the VS Code Terminal:

    cp .env.docker.example .env.docker.secret

1.11.2. (UPD) Start the services using Docker Compose

Note

Docker Compose reads environment variables from .env.docker.secret and uses them to configure the containers defined in docker-compose.yml.

  1. To start the services,

    run in the VS Code Terminal:

    docker compose --env-file .env.docker.secret up --build

    Wait for the services to start. You should see log output from the app, postgres, pgadmin, and caddy containers.

    Troubleshooting

    Port conflict (port is already allocated)

    Stop the process that uses the port, then retry.

    Containers exit immediately

    To rebuild all containers from scratch,

    run in the VS Code Terminal:

    docker compose --env-file .env.docker.secret down -v
docker compose --env-file .env.docker.secret up --build

    Image pull fails

    Check your internet connection. If you are behind a proxy, configure Docker to use it.

Note

The database is initialized from backend/app/data/init.sql only on the first start of the PostgreSQL container.

If you need to re-initialize the database (e.g., after pulling upstream changes to init.sql), see Resetting the database.

1.12. Observe containers and services

1.12.1. (UPD) Open a new VS Code Terminal

  1. Open a new VS Code Terminal.

1.12.2. (UPD) List running containers

  1. To list running containers,

    run in the VS Code Terminal:

    docker compose --env-file .env.docker.secret ps

  2. To look at services and their statuses specifically,

    docker compose --env-file .env.docker.secret ps --format "table {{.Service}}\t{{.Status}}"

    You should see a similar output:

    SERVICE    STATUS
app        Up 3 minutes
caddy      Up 3 minutes
pgadmin    Up 3 minutes
postgres   Up 3 minutes (healthy)

1.12.3. (UPD) See logs of the running services

  1. To see logs for all services,

    run in the VS Code Terminal:

    docker compose --env-file .env.docker.secret logs

    You should see log output from the app, postgres, pgadmin, and caddy services.

  2. To see logs for the postgres service,

    run in the VS Code Terminal:

    docker compose --env-file .env.docker.secret logs postgres

    You should see only the postgres service logs, including a line like database system is ready to accept connections.

1.13. (UPD) Set up Swagger UI

  1. Open Swagger UI.

    You should see the Swagger UI page with the API documentation.

    Swagger UI

1.14. Set up pgAdmin

1.14.1. (UPD) Connect pgAdmin to the database

Note

pgAdmin takes 2-3 minutes to start after you have started the services.

  1. Open pgAdmin.
  2. Connect pgAdmin to the PostgreSQL server.
Troubleshooting

pgAdmin page does not load

pgAdmin takes 2–3 minutes to start. Wait and refresh the page.

Connection to the server refused

Make sure the services are running. Go back to step 1.11.2 and start them.

1.14.2. (UPD) Inspect the tables

  1. Browse the data in the interacts table.

    You should see rows of data stored in the database.

    Interaction logs

    These are records of what learners did with items (courses, labs, tasks, steps). learners attempted, completed or just viewed items.

  2. Verify that the following tables also exist:

    • item
    • learner

1.15. (UPD) Stop the services

  1. Check that the current directory is se-toolkit-lab-4.
  2. Stop and remove all containers and volumes.

1.16. (UPD) Set up a coding agent

A coding agent can help you write code, explain concepts, and debug issues.

Qwen request Qwen response

1.17. Set up the autochecker

Set up the autochecker

1.18. Check the setup using the autochecker

Check the task using the autochecker Telegram bot.

2. Optional steps

These enhancements can make your life easier:

2.1. (UPD) Set up Nix

  1. (Optional) Read about Nix.
  2. Set up Nix.

2.2. (UPD) Set up direnv

  1. (Optional) Read about direnv.
  2. Set up Nix.
  3. Set up direnv.

2.3. Learn to go back after clicking a link

Note

Shortcuts for going back after clicking a link:

  • VS Code — see the shortcut.
  • Firefox — Alt+ArrowLeft.
  • Other browsers — google.

2.4. Set up the shell prompt

Starship shows your current Git branch, status, and other useful info directly in your shell prompt in almost any terminal, including the VS Code Terminal.

Complete these steps:

  1. Install Starship.

  2. Open the VS Code Terminal.

    You should see something similar to this:

    Starship in the VS Code Terminal

2.5. Customize the Source Control

  1. Open the Source Control.

  2. Click three dots to the right of SOURCE CONTROL.

  3. Put checkmarks only near Changes and GitLens to see only these views.

    Changes and GitLens

2.6. Get familiar with GitLens

GitLens helps you work with Git in VS Code.

Complete these steps:

  1. See all branches.
  2. Look at the commit graph.
  3. Inspect the current branch.
  4. Inspect the remotes.

2.7. Create a label for tasks

Labels help you filter and organize issues.

With a task label, you can see in one view all issues created for lab tasks.

Tip

If you create the task label before creating issues, your issues will have this label automatically as configured in the issue form.

Complete these steps:

  1. Create the task label.
  2. Add the label to issues.
  3. See all issues with the label.

2.8. View Markdown files in VS Code

If you want to view README.md and other Markdown files in VS Code instead of on GitHub:

  1. Install the recommended VS Code extensions.
  2. Open the file: README.md.
  3. Open the Markdown preview.