Skip to content

DEVELOPMENT.md

Latest commit

 

History

History
89 lines (70 loc) · 5.45 KB

DEVELOPMENT.md

File metadata and controls

89 lines (70 loc) · 5.45 KB

Development

Setup

With Docker (easiest)

  1. git clone https://github.com/KoelLabs/server.git
    • On Windows, install Git first. Recommended: use the included git-bash to run the commands in the rest of the instructions.
  2. Install Docker and Docker Compose
    • Docker Desktop for Mac or brew install --cask docker with Homebrew
      • If it repeatedly complains about the daemon not running, make sure Docker Desktop is running and add export DOCKER_HOST=unix:///Users/$USER/Library/Containers/com.docker.docker/Data/docker.raw.sock to your shell profile (e.g. ~/.zshrc)
    • Docker Desktop for Windows or choco install docker-desktop with Chocolatey
    • Docker Engine for Linux or sudo apt install docker.io with APT on Ubuntu
  3. Duplicate the .env.example file and rename it to .env. Fill in the necessary environment variables.
    • You can find your HF_TOKEN on your Settings Page. It just needs read access to gated repos.
  4. Run the application
    • . ./scripts/docker-run-dev.sh to start the development server
    • If http://localhost:8080 doesn't automatically open in your browser, open it manually
    • ctrl+c to stop the server

To add new dependencies, update the requirements.txt file and run . ./scripts/docker-run-dev.sh again.

Directly on your machine (runs fastest)

  1. git clone https://github.com/KoelLabs/server.git
    • On Windows, install Git first. Recommended: use the included git-bash to run the commands in the rest of the instructions.
  2. Install Python 3.8.10 or higher
    • Install pyenv
    • Run pyenv install 3.10.12
    • Pyenv should automatically use this version in this directory. If not, run pyenv local 3.10.12
  3. Create a virtual environment
    • Run python -m venv ./venv to create it
    • Run . venv/bin/activate when you want to activate it
      • Run deactivate when you want to deactivate it
    • Pro-tip: select the virtual environment in your IDE, e.g. in VSCode, click the Python version in the bottom left corner and select the virtual environment
  4. Install dependencies
  5. Duplicate the .env.example file and rename it to .env. Fill in the necessary environment variables.
    • You can find your HF_TOKEN on your Settings Page. It just needs read access to gated repos.
  6. Run the server
    • Run python src/server.py to start the development server
    • Open your browser to http://localhost:8080
    • ctrl+c to stop the server

To save dependencies you pip install, then run pip freeze > requirements.txt.

Formatting, Linting, Automated Tests and Secret Scanning

All checks are run as github actions when you push code. You can also run them manually with . scripts/alltests.sh.

  • We use Black for formatting. It is recommended you integrate it with your IDE to run on save. You can run it manually with black ..

  • We scan the repo for leaked secrets with gitleaks. You can run it manually with gitleaks detect.

  • We use zizmor for static analysis and security audits of github actions. You can run it manually with zizmor ..

  • We use pytest for testing. Tests live in the tests directory and can be run with pytest. You can run a specific test with pytest tests/test_example.py::test_example. Place all fixtures in tests/conftest.py.

File Structure

server/
├── .github/                     # Actions and Templates
├── scripts/                     # Shell+Python scripts
├── src/                         # Flask server
│   ├── static/                  # Test client
│   ├── feedback.py              # Feedback logic
│   └── server.py                # Routes and setup
├── tests/                       # Automated tests
│   ├── conftest.py              # Pytest fixtures
│   └── test_*.py                # Test files
├── .env.example                 # Example .env file
├── .gitignore                   # Git ignore rules
├── requirements.txt             # Python dependencies
├── CONTRIBUTING.md              # Guidelines
├── DEVELOPMENT.md               # Development setup
├── LICENSE                      # License information
└── README.md                    # Readme

Branches

main is the default branch containing the latest code (this is where pull requests will be merged in).

test will automatically deploy to the test environment on push/merge.

prod will automatically deploy to the production environment on push/merge.