Skip to content

03. Dev Environment

In this section, you'll set up your development environment, create a new branch, and initialize a basic FastAPI application.

3.1 Open Repository in Codespaces

  1. Navigate to your GitHub repository
  2. Click the green Code button
  3. Select the Codespaces tab
  4. Click Create codespace on main

Wait for the codespace to initialize. This may take a few minutes.

3.2 Set Up Git Branch and Project Board

Update Project Board

Before starting work on any issue:

  1. Go to your repository on GitHub
  2. Navigate to the Projects tab
  3. Open your project board
  4. Find the issue card for "Initial FastAPI App" (should be in "Todo" or "Backlog" column)
  5. Drag the card to the "In Progress" column

This helps your team see what you're currently working on.

Create the Branch

Create a new branch for your work:

Using VS Code UI:

  1. In VS Code's Source Control panel, click on the branch name at the bottom left (shows current branch)
  2. Select Create new branch
  3. Name it fastapi-setup
  4. Press Enter to create and switch to the new branch

Using Terminal:

Alternatively, you can run the following command in the terminal:

git checkout -b fastapi-setup

3.3 Add .gitignore and .dockerignore

It is important to exclude unnecessary files from your specific environment (like virtual environments, cache, etc.) from git.

  1. Create a file named .gitignore in the root directory.
  2. Add the following content:
__pycache__/
*.py[cod]
*$py.class
.pytest_cache/
.coverage
htmlcov/
dist/
build/
*.egg-info/
.env
.venv
env/
venv/
venv*/
.vscode/
*.log
  1. Create a file named .dockerignore in the root directory.
  2. Add the following content:
__pycache__/
*.py[cod]
*$py.class
.pytest_cache/
.git/
.github/
.vscode/
.venv/
venv/
dist/
*.egg-info/
.coverage
htmlcov/
.env

3.4 Initialize Python Project with UV

UV is a modern Python package manager and virtual environment tool.

Run the following command in the terminal:

First, install UV with this command:

curl -LsSf https://astral.sh/uv/install.sh | sh

Then, initialize the project:

uv init

This creates the basic Python project structure with an app package.

3.5 Move main.py to app Directory

Using VS Code UI:

  1. In the Explorer panel, create a new folder named app
  2. Drag and drop main.py into the app folder
  3. Create an empty __init__.py file inside the app folder to make it a package

Using Terminal: Alternatively, you can run the following commands in the terminal:

mkdir app
mv main.py app/
touch app/__init__.py

3.6 Update pyproject.toml

Open pyproject.toml and add the following section at the end of the file:

[tool.uv]
package = true

[tool.pytest.ini_options]
filterwarnings = [
  # Ignore deprecations from vbuild using pkgutil.find_loader (pending upstream fix)
  "ignore:'pkgutil.find_loader' is deprecated:DeprecationWarning:vbuild"
]

[tool.semantic_release]
version_toml = ["pyproject.toml:project.version"]
branch = "main"
allow_zero_version = true
major_on_zero = false
upload_to_pypi = false
upload_to_release = true
commit_version_number = true
tag_commit = true
changelog_file = "CHANGELOG.md"
build_command = "python -m pip install uv && python -m uv build"

Run the following command to update project:

uv sync

[!NOTE] If you are working in Codespaces, you might see a warning during uv sync. This is often harmless in the Codespace environment, provided the installation completes.

3.7 Install Dependencies

Install FastAPI

FastAPI is a modern, fast (high-performance), web framework for building APIs with Python. The [standard] extras include uvicorn (ASGI server), pydantic, and other essential dependencies.

uv add "fastapi[standard]"

3.8 Create Basic FastAPI App

  1. Open app/main.py
  2. Replace the contents with the following code:
from fastapi import FastAPI

app = FastAPI(title="CSE120 GitHub Workshop")

3.9 Run the Development Server

Start the FastAPI development server:

uv run fastapi dev

[!WARNING] Check if the server is already running! If you try to run this command while another server instance is already active (e.g., in another terminal), you will get an error (Address already in use). Make sure to stop any existing servers (Ctrl+C) before starting a new one.

You should see output indicating the server is running.

3.10 View the API Documentation

In Codespaces, you'll get a notification about port forwarding and opening the port in a browser.

Alternatively, you can manually open the port: 1. Click on the PORTS tab in VS Code (in the bottom panel next to TERMINAL by default) 2. Find port 8000 and click the globe icon to open in browser 3. Navigate to /docs (append /docs to the URL that was opened) to see the interactive API documentation

[!TIP] You should see the automated Swagger UI documentation page, which allows you to inspect and test your API endpoints.

3.11 Commit and Push Changes

Navigate back to Codespaces.

Make your first commit:

VS Code UI: 1. Go to the Source Control panel (icon with three branches) 2. Stage all changes by clicking the + icon next to Changes 3. In the message box, type: 

feat: add initial FastAPI app 

closes #<issue-number>

Note: Replace `<issue-number>` with the actual issue number, e.g., `1`.
  1. Click the checkmark icon to commit

Terminal:

Alternatively, you can run the following commands in the terminal:

git add .
git commit -m "feat: add initial FastAPI app"
git push origin fastapi-setup

Note: The commit message follows conventional commits format and references the issue number.

Learn more

Understanding Conventional Commits

Conventional Commits provide a standardized format for commit messages:

  • feat: A new feature
  • fix: A bug fix
  • docs: Documentation only changes
  • style: Changes that don't affect code meaning (formatting, etc.)
  • refactor: Code change that neither fixes a bug nor adds a feature
  • test: Adding or correcting tests
  • chore: Changes to build process or auxiliary tools

Format: <type>(<scope>): <subject>

Example: feat(api): add health check endpoint

Closing Issues with Commits

Use keywords in commit messages to automatically close issues: - closes #1 or fixes #1 or resolves #1 - GitHub will automatically close the referenced issue when the commit is merged into the main branch. - Note: The issue will only be closed if the commit is pushed to the main branch, e.g. via a merge of a PR.*

Useful Resources