Skip to content

Commit b1aeb2b

Browse files
monok8imonok8i
committed
docs: add documentation about available options to clone and use template
1 parent 7916e13 commit b1aeb2b

File tree

3 files changed

+160
-1
lines changed

3 files changed

+160
-1
lines changed

‎docs/usage/index.md‎

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
# Quickstart
2+
3+
This section describes how to get started with this project: how to clone or create your own copy, and how to launch the app in different ways (locally, with Docker, or in Codespaces).
4+
5+
---
6+
7+
## How to Get the Project
8+
9+
!!! tip "!"
10+
=== "Option A: Use as a Template"
11+
12+
**If you want to start your own project based on this boilerplate, use GitHub’s “Use this template” button:**
13+
14+
!!! example "workflow"
15+
1. Go to the [repository page](https://github.com/python-boilerplate/uv-template).
16+
2. Click **Use this template** (top right).
17+
3. Create a new repository under your GitHub account.
18+
4. Clone your new repository:
19+
```bash
20+
git clone https://github.com/<your-username>/<your-new-repo>.git
21+
cd <your-new-repo>
22+
```
23+
24+
=== "Option B: Clone Directly"
25+
26+
**If you want to contribute here or just try the boilerplate as-is:**
27+
28+
!!! example "workflow"
29+
1. Go to the [repository page](https://github.com/python-boilerplate/uv-template).
30+
2. Click **Code > Download ZIP** (or clone the repo).
31+
3. Extract the ZIP file (if used).
32+
4. Navigate into the project directory:
33+
```bash
34+
cd uv-template
35+
```
36+
37+
---
38+
39+
## How to Run the Project
40+
41+
!!! tip "!"
42+
=== "Option 1: GitHub Codespaces / Dev Containers (Zero Setup)"
43+
44+
!!! example "workflow"
45+
1. On GitHub, click **Code > Codespaces > Create codespace on main**.
46+
2. _Or_, open the project in VS Code with the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers).
47+
3. Choose “Reopen in Container” when prompted.
48+
4. Wait while all dependencies and tools are installed automatically.
49+
5. You can now use all `make` commands, run the app, tests, etc.
50+
51+
=== "Option 2: Local Development (No Docker)"
52+
53+
**Requirements:** Python 3.10+, [uv](https://github.com/astral-sh/uv) (or pip if you know what you’re doing).
54+
55+
!!! example "workflow"
56+
1. Install [uv](https://github.com/astral-sh/uv) (recommended):
57+
```bash
58+
curl -LsSf https://astral.sh/uv/install.sh | sh
59+
```
60+
2. Install dependencies & set up pre-commit hooks:
61+
```bash
62+
make init
63+
```
64+
3. Run the app:
65+
```bash
66+
make run
67+
```
68+
4. Run tests, linter, formatter as needed:
69+
```bash
70+
make test
71+
make lint
72+
make format
73+
```
74+
75+
=== "Option 3: Local Development with Docker (Dev Environment)"
76+
77+
**Best for:** Consistent dev environment, works anywhere Docker runs.
78+
79+
!!! example "workflow"
80+
1. Build the development Docker image:
81+
```bash
82+
make dev-build
83+
```
84+
2. Start the dev container (in background):
85+
```bash
86+
make dev-up
87+
```
88+
3. Enter a shell in the container (if needed):
89+
```bash
90+
make dev-exec
91+
```
92+
4. View logs, stop, or remove the container as needed:
93+
```bash
94+
make dev-logs
95+
make dev-stop
96+
make dev-down
97+
```
98+
!!! info "Dev Docker specifics"
99+
- Uses `dev.Dockerfile` and `dev.dockerignore`
100+
- Before building it runs `cp dev.dockerignore .dockerignore` to specify files to ignore
101+
- Loads environment from `.env.development`
102+
- Supports hot reload and development tools
103+
104+
=== "Option 4: Production Docker Image"
105+
106+
**Best for:** Testing production-like runs or deployment.
107+
108+
!!! example "workflow"
109+
1. Build the production image:
110+
```bash
111+
make prod-build
112+
```
113+
2. Run the production container:
114+
```bash
115+
make prod-run
116+
```
117+
3. Enter a shell in the container (if needed):
118+
```bash
119+
make prod-exec
120+
```
121+
4. Run container with `bash` or view logs:
122+
```bash
123+
make prod-bash # temporary, with .env.production and with --rm flag
124+
make prod-logs
125+
```
126+
127+
!!! info "Prod Docker specifics"
128+
- Uses `prod.Dockerfile` and `prod.dockerignore`
129+
- Before building it runs `cp prod.dockerignore .dockerignore` to specify files to ignore
130+
- Loads environment from `.env.production`
131+
- Optimized for minimal size and performance
132+
---
133+
134+
## Useful Tips
135+
136+
- All common tasks (init, test, lint, format, docs, etc.) are available as simple `make` commands.
137+
- See [docs/usage/commands.md](./commands.md) for the full list.
138+
- Environments and secrets are configured via `.env.*` files (see `.env.example`).
139+
- The project is ready for CI/CD with GitHub Actions and GitLab CI out of the box.
140+
141+
---
142+
143+
## Troubleshooting
144+
145+
- If you have permission errors with git hooks, run:
146+
```bash
147+
chmod +x .git/hooks/*
148+
```
149+
- For Docker issues, ensure Docker is running and you have permissions (try `sudo` if needed).
150+
- For Codespaces/Dev Containers, see the [Dev Containers docs](../features/devcontainers.md).
151+
152+
---
153+
154+
## More Info
155+
156+
- See [Features](../features/index.md) for detailed explanations of tools and setup.
157+
- See [Project Structure](../reference/project_structure.md) for a file/folder overview.
158+
159+
---

‎docs/usage/options.md‎

Whitespace-only changes.

‎mkdocs.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ nav:
99
- License: home/license.md
1010
- Contributing: home/contributing.md
1111
- Usage:
12-
- Options: usage/options.md
12+
- Options: usage/index.md
1313
- Commands: usage/commands.md
1414
- Features:
1515
- Overview: features/index.md

0 commit comments

Comments
 (0)