|
1 |
| -# Boilerplate code for Brewblox services |
| 1 | +# USB Proxy for Spark devices |
2 | 2 |
|
3 |
| -There is some boilerplate code involved when creating a Brewblox service. |
4 |
| -This repository can be used as a template to get started. |
5 |
| - |
6 |
| -You're free to use whatever editor or IDE you like, but we preconfigured some useful settings for [Visual Studio Code](https://code.visualstudio.com/). |
7 |
| - |
8 |
| -Everything listed under **Required Changes** must be done before the package works as intended. |
9 |
| - |
10 |
| -## How to use |
11 |
| - |
12 |
| -- Install required dependencies (see below) |
13 |
| -- Fork this repository to your own Github account or project. |
14 |
| -- Follow all steps outlined under the various **Required Changes**. |
15 |
| -- Start coding your service =) |
16 |
| - - To test, run `poetry run pytest` |
17 |
| - - To lint, run `poetry run flake8` |
18 |
| - |
19 |
| -## Install |
20 |
| - |
21 |
| -Install the Python dev environment: <https://brewblox.com/dev/python_env.html> |
22 |
| - |
23 |
| -During development, you need to have your environment activated. |
24 |
| -When it is activated, your terminal prompt is prefixed with `(.venv)`. |
25 |
| - |
26 |
| -Visual Studio code with suggested settings does this automatically whenever you open a .py file. |
27 |
| -If you prefer using a different editor, you can do it manually by running: |
28 |
| - |
29 |
| -```bash |
30 |
| -poetry shell |
31 |
| -``` |
32 |
| - |
33 |
| -Install [Docker](https://www.docker.com/101-tutorial): |
34 |
| - |
35 |
| -```bash |
36 |
| -curl -sL get.docker.com | sh |
37 |
| - |
38 |
| -sudo usermod -aG docker $USER |
39 |
| - |
40 |
| -reboot |
41 |
| -``` |
42 |
| - |
43 |
| -## Files |
44 |
| - |
45 |
| ---- |
46 |
| - |
47 |
| -### [pyproject.toml](./pyproject.toml) |
48 |
| - |
49 |
| -The [pyproject](https://python-poetry.org/docs/pyproject/) file contains all kinds of Python settings. |
50 |
| -For those more familiar with Python packaging: it replaces the following files: |
51 |
| - |
52 |
| -- `setup.py` |
53 |
| -- `MANIFEST.in` |
54 |
| -- `requirements.txt` |
55 |
| - |
56 |
| -**Required Changes:** |
57 |
| - |
58 |
| -- Change the `name` field to your package name. This is generally the same as the repository name, but with any dash (`-`) characters replaced with underscores (`_`). |
59 |
| -- Change the `authors` field to your name and email. |
60 |
| -- Change the `description` field to a short description of your service. |
61 |
| - |
62 |
| ---- |
63 |
| - |
64 |
| -### [.editorconfig](./.editorconfig) |
65 |
| - |
66 |
| -This file contains [EditorConfig](https://editorconfig.org/) configuration for this project. \ |
67 |
| -Among other things, it describes per file type whether it uses tabs or spaces. |
68 |
| - |
69 |
| -For a basic service, you do not need to change anything in this file. |
70 |
| -However, it is recommended to use an editor that recognizes and uses `.editorconfig` files. |
71 |
| - |
72 |
| ---- |
73 |
| - |
74 |
| -### [README.md](./README.md) |
75 |
| - |
76 |
| -Your repository readme (this file). It will automatically be displayed in Github. |
77 |
| - |
78 |
| -**Required Changes:** |
79 |
| - |
80 |
| -- Add all important info about your package here. What does your package do? How do you use it? What is your favorite color? |
81 |
| - |
82 |
| ---- |
83 |
| - |
84 |
| -### [your_package/](./your_package/) |
85 |
| - |
86 |
| -The source code directory. The directory name is used when importing your code in Python. |
87 |
| - |
88 |
| -Here you can find both code scaffolding, and examples for common features. |
89 |
| - |
90 |
| -**Required Changes:** |
91 |
| - |
92 |
| -- Rename to the desired module name. This name can't include "`-`" characters. |
93 |
| - |
94 |
| ---- |
95 |
| - |
96 |
| -### [models.py](./your_package/models.py) |
97 |
| - |
98 |
| -[Pydantic](https://docs.pydantic.dev) data models. |
99 |
| -This includes the service configuration, which is set through environment variables. |
100 |
| - |
101 |
| -**Required Changes:** |
102 |
| - |
103 |
| -- Change the default service name value from `your_package` to your service name. |
104 |
| -- Change the default env prefix from `your_package_` to your preferred prefix. Typically this is either package name or service name. |
105 |
| - |
106 |
| ---- |
107 |
| - |
108 |
| -### [test/](./test/) |
109 |
| - |
110 |
| -The test code shows how to setup tests and call endpoints. |
111 |
| -This includes multiple tricks for testing async code with pytest. |
112 |
| -You can remove the files if you no longer need them. |
113 |
| - |
114 |
| -**Required Changes:** |
115 |
| - |
116 |
| -- Change `your_package` imports to your package name. |
117 |
| - |
118 |
| ---- |
119 |
| - |
120 |
| -### [Dockerfile](./Dockerfile) |
121 |
| - |
122 |
| -A docker file for your service. Building the Dockerfile installs your Python distributable, and creates a Docker image. |
123 |
| - |
124 |
| -**Required Changes:** |
125 |
| - |
126 |
| -- Change `your_package` to your package name. |
127 |
| - |
128 |
| ---- |
129 |
| - |
130 |
| -### [entrypoint.sh](./entrypoint.sh) |
131 |
| - |
132 |
| -This script is the entrypoint for the Docker container. |
133 |
| -It starts [Uvicorn](https://www.uvicorn.org/), the ASGI web server that runs the service code. |
134 |
| - |
135 |
| -**Required Changes:** |
136 |
| - |
137 |
| -- Change `your_package` to your package name. |
138 |
| - |
139 |
| ---- |
140 |
| - |
141 |
| -### [tasks.py](./tasks.py) |
142 |
| - |
143 |
| -[Invoke](https://www.pyinvoke.org/) is a convenient way to add build scripts. |
144 |
| - |
145 |
| -By default, four tasks are available: |
146 |
| - |
147 |
| -- **dist** generates the Python distributable that can then be used to build a Docker image. |
148 |
| -- **prepx** creates a Docker builder for multiplatform images. |
149 |
| -- **build** creates a local Docker image for testing. This image is not uploaded. |
150 |
| -- **release** creates and uploads a multiplatform image. |
151 |
| - |
152 |
| -**Required Changes:** |
153 |
| - |
154 |
| -- Change `IMAGE` from `ghcr.io/you/your-package` to your Docker image name. |
155 |
| - |
156 |
| ---- |
157 |
| - |
158 |
| -### [build.yml](./.github/workflows/build.yml) |
159 |
| - |
160 |
| -Github can automatically test, build, and deploy all commits you push. |
161 |
| -When enabled, this configuration will run tests, and then build a Docker image. |
162 |
| - |
163 |
| -By default, the image is pushed to the Github Container Registry (ghcr.io). |
164 |
| -If you want to use an alternative registry like Docker Hub, you can do this by changing the login step, |
165 |
| -and then omitting the `ghcr.io/` prefix to your image. |
166 |
| - |
167 |
| -When first pushed, Github sets the visibility of the image to `Internal`. |
168 |
| -To make it publicly available: |
169 |
| - |
170 |
| -- Navigate to the Github page of your repository. |
171 |
| -- Click on the image name under "Packages" on the right-hand side of the repository page. |
172 |
| -- Click on "Package settings" on the right-hand side of the package page. |
173 |
| -- Scroll down to the "Danger Zone", and click "Change package visibility". |
174 |
| -- Set visibility to "Public", and type the name of the image to confirm. |
175 |
| - |
176 |
| -**Required Changes:** |
177 |
| - |
178 |
| -- Remove the `if: false` line in the `build` job to enable CI. |
179 |
| -- Set the `DOCKER_IMAGE` variable to your Docker image name. |
180 |
| - |
181 |
| -That's it. Happy coding! |
| 3 | +This service scans for connected Spark USB devices, and then forwards the connection over TCP. |
0 commit comments