9.0 KiB
Website Template
Welcome to our website template repository! This template is designed to help you and your team build high-quality websites efficiently. We've carefully chosen the technologies to make development smooth and enjoyable. Here's what you can expect from this template:
Frontend: Our frontend is powered by React NextJS, a popular and versatile framework for building web applications.
Backend: For the backend, we use Python along with the FastAPI framework. To ensure seamless communication between the frontend and backend, we generate an openapi.json
file from the Python code, which defines the REST API. This file is then used with Orval to generate TypeScript bindings for the REST API. We're committed to code correctness, so we use mypy to ensure that our Python code is statically typed correctly. For backend testing, we rely on pytest.
Continuous Integration (CI): We've set up a CI bot that rigorously checks your code using the quality assurance (QA) tools mentioned above. If any errors are detected, it will block pull requests until they're resolved.
Dependency Management: We use the Nix package manager to manage dependencies and ensure reproducibility, making your development process more robust.
Supported Operating Systems
- Linux
- macOS
Getting Started with the Development Environment
Let's get your development environment up and running:
-
Install Nix Package Manager:
- You can install the Nix package manager by either downloading the Nix installer or running this command:
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
- You can install the Nix package manager by either downloading the Nix installer or running this command:
-
Install direnv:
- Download the direnv package from here or run the following command:
curl -sfL https://direnv.net/install.sh | bash
- Download the direnv package from here or run the following command:
-
Add direnv to your shell:
- Direnv needs to hook into your shell to work. You can do this by executing following command:
echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc && echo 'eval "$(direnv hook bash)"' >> ~/.bashrc && eval "$SHELL"
-
Clone the Repository and Navigate:
- Clone this repository and navigate to it.
-
Allow .envrc:
- When you enter the directory, you'll receive an error message like this:
direnv: error .envrc is blocked. Run `direnv allow` to approve its content
- Execute
direnv allow
to automatically execute the shell script.envrc
when entering the directory.
- When you enter the directory, you'll receive an error message like this:
-
Build the Backend:
- Go to the
pkgs/clan-cli
directory and execute:direnv allow
- Wait for the backend to build.
- Go to the
-
Start the Backend Server:
- To start the backend server, execute:
clan webui --reload --no-open --log-level debug
- The server will automatically restart if any Python files change.
- To start the backend server, execute:
-
Build the Frontend:
- In a different shell, navigate to the
pkgs/ui
directory and execute:direnv allow
- Wait for the frontend to build.
NOTE: If you have the error "@clan/colors.json" you executed
npm install
, please do not do that.direnv reload
will handle dependency management. Please delete node_modules withrm -rf node_modules
. - In a different shell, navigate to the
-
Start the Frontend:
- To start the frontend, execute:
npm run dev
- Access the website by going to http://localhost:3000.
- To start the frontend, execute:
Setting Up Your Git Workflow
Let's set up your Git workflow to collaborate effectively:
-
Register Your Gitea Account Locally:
- Execute the following command to add your Gitea account locally:
tea login add
- Fill out the prompt as follows:
- URL of Gitea instance:
https://gitea.gchq.icu
- Name of new Login [gitea.gchq.icu]:
gitea.gchq.icu:7171
- Do you have an access token? No
- Username: YourUsername
- Password: YourPassword
- Set Optional settings: No
- URL of Gitea instance:
- Execute the following command to add your Gitea account locally:
-
Git Workflow:
- Add your changes to Git using
git add <file1> <file2>
. - Run
nix fmt
to lint your files. - Commit your changes with a descriptive message:
git commit -a -m "My descriptive commit message"
. - Make sure your branch has the latest changes from upstream by executing:
git fetch && git rebase origin/main --autostash
- Use
git status
to check for merge conflicts. - If conflicts exist, resolve them. Here's a tutorial for resolving conflicts in VSCode.
- After resolving conflicts, execute
git merge --continue
and repeat step 5 until there are no conflicts.
- Add your changes to Git using
-
Create a Pull Request:
- To automatically open a pull request that gets merged if all tests pass, execute:
merge-after-ci
- To automatically open a pull request that gets merged if all tests pass, execute:
-
Review Your Pull Request:
- Visit https://gitea.gchq.icu and go to the project page. Check under "Pull Requests" for any issues with your pull request.
-
Push Your Changes:
- If there are issues, fix them and redo step 2. Afterward, execute:
git push origin HEAD:YourUsername-main
- This will directly push to your open pull request.
- If there are issues, fix them and redo step 2. Afterward, execute:
Debugging
When working on the backend of your project, debugging is an essential part of the development process. Here are some methods for debugging and testing the backend of your application:
Test Backend Locally in Devshell with Breakpoints
To test the backend locally in a development environment and set breakpoints for debugging, follow these steps:
- Run the following command to execute your tests and allow for debugging with breakpoints:
You can placepytest -n0 -s --maxfail=1
breakpoint()
in your Python code where you want to trigger a breakpoint for debugging.
Test Backend Locally in a Nix Sandbox
To run your backend tests in a Nix sandbox, you have two options depending on whether your test functions have been marked as impure or not:
Running Tests Marked as Impure
If your test functions need to execute nix build
and have been marked as impure because you can't execute nix build
inside a Nix sandbox, use the following command:
nix run .#impure-checks
This command will run the impure test functions.
Running Pure Tests
For test functions that have not been marked as impure and don't require executing nix build
, you can use the following command:
nix build .#checks.x86_64-linux.clan-pytest --rebuild
This command will run all pure test functions.
Running schemathesis fuzzer on GET requests
nix run .#runSchemaTests
If you want to test more request types edit the file checks/impure/flake-module.nix
Inspecting the Nix Sandbox
If you need to inspect the Nix sandbox while running tests, follow these steps:
-
Insert an endless sleep into your test code where you want to pause the execution. For example:
import time time.sleep(3600) # Sleep for one hour
-
Use
cntr
andpsgrep
to attach to the Nix sandbox. This allows you to interactively debug your code while it's paused. For example:cntr exec -w your_sandbox_name psgrep -a -x your_python_process_name
These debugging and testing methods will help you identify and fix issues in your backend code efficiently, ensuring the reliability and robustness of your application.
For more information on testing read property and contract based testing
Using this Template
To make the most of this template:
-
Set up a new Gitea account named
ui-asset-bot
. Generate an access token with all access permissions and set it undersettings/actions/secrets
as a secret calledBOT_ACCESS_TOKEN
.- Also, edit the file
.gitea/workflows/ui_assets.yaml
and change theBOT_EMAIL
variable to match the email you set for that account. Gitea matches commits to accounts by their email address, so this step is essential.
- Also, edit the file
-
Create a second Gitea account named
merge-bot
. Edit the filepkgs/merge-after-ci/default.nix
if the name should be different. Under "Branches," set the main branch to be protected and addmerge-bot
to the whitelisted users for pushing. Set the unprotected file pattern to**/ui-assets.nix
.- Enable the status check for "build / test (pull_request)."
-
Add both
merge-bot
andui-asset-bot
as collaborators.- Set the option to "Delete pull request branch after merge by default."
- Also, set the default merge style to "Rebase then create merge commit."
With this template, you're well-equipped to build and collaborate on high-quality websites efficiently. Happy coding!.
API guidelines
see ./api-guidelines