doc: document how to use tesseract serve --network parameter#530
doc: document how to use tesseract serve --network parameter#530
tesseract serve --network parameter#530Conversation
zmheiko
requested review from
apaleyes,
dionhaefner,
jpbrodrick89 and
xalelax
as code owners
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #530 +/- ##
=======================================
Coverage 66.77% 66.77%
=======================================
Files 32 32
Lines 4409 4409
Branches 730 730
=======================================
Hits 2944 2944
Misses 1226 1226
Partials 239 239 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
|
|
||
| `--network=host` makes a container share the host's network stack, which can be a convenient alternative to creating an explicit Docker network. However, it does not work correctly on all platforms. On macOS and Windows, Docker Desktop runs the Docker daemon inside a lightweight VM. The "host" from the daemon's perspective is that VM, not your actual machine, so `--network=host` gives the container access to the VM's network rather than your host's. This means services running on your machine are not reachable via `localhost` from inside the container, and the pattern of calling Tesseracts by host address will not work as expected. | ||
|
|
||
| At the moment `--network=host` works as intended only on Linux, where the Docker daemon runs directly on the host. Alternatives to Docker Desktop that run the daemon more natively, such as [Colima](https://github.com/abiosoft/colima), may also support host networking correctly. For cross-platform workflows, prefer creating an explicit Docker network as shown above. |
There was a problem hiding this comment.
Have we tried this? IIUC, Docker Desktop will also run containerized on Linux, so it really boils down to whether you use Docker Desktop or Engine.
There was a problem hiding this comment.
Good catch, I confused Docker Desktop and Engine here. I have not tested it recently, but I experimented with it when Linus and I first encountered these failures. Back then I got it working on Linux. I never installed Docker Desktop on the Azure VM so it must have just been Engine.
So yeah, this is wrong and needs rephrasing. I'll double-check that the setup on Linux indeed works and change the paragraph accordingly.
|
Thanks @zmheiko ! Do you think we should pull the trigger and also create networks passed with |
The only drawback that I'm seeing is that the user might pass a wrong network name (e.g. XXY), misses the emitted "new network XXY created" message (that I assume we'd add), and then wonders why the new Tesseract cannot communicate with the existing ones in network XXX. So maybe an additional |
dionhaefner
changed the title
tesseract serve --network parameter
|
I updated the documentation and added a Ping-Tesseract that can be used to check if networking works. I tested it on Mac (with Colima, but this should behave the same way as Docker Desktop) and a Azure Linux VM (with Docker Engine). As expected, with |
| To verify whether outbound network access works in your environment, you can use the [`examples/ping`](https://github.com/pasteurlabs/tesseract-core/tree/main/examples/ping) Tesseract, which fetches a URL and reports whether it was reachable: | ||
|
|
||
| ```bash | ||
| $ tesseract build ./examples/ping | ||
| $ tesseract run ping:latest apply '{"inputs": {"url": "https://pasteurlabs.ai/"}}' | ||
| ``` | ||
|
|
||
| To specifically test if `--network=host` works, start a local webserver and check whether containers can reach it. First set up the server: | ||
|
|
||
| ```bash | ||
| $ python3 -m http.server 9999 | ||
| ``` | ||
|
|
||
| Then, while the server is running, target the ping Tesseract at it: | ||
|
|
||
| ```bash | ||
| $ tesseract run --network=host ping:latest apply '{"inputs": {"url": "http://localhost:9999"}}' | ||
| ``` | ||
|
|
There was a problem hiding this comment.
This is a nice touch but I'm not sure if it's worth it to add yet another example tested on every commit just for this use case. For now the section above it seems appropriate: Here is the recommended way to do it; if you feel like you must use host beware because there be dragons. So unless you have strong feelings regarding the ping Tesseract I suggest we drop it for now.
There was a problem hiding this comment.
No strong feelings. I used it for testing and thought I might as well add it.
| You can create a Docker network and attach Tesseracts to it using the `--network` flag. | ||
|
|
||
| ```bash | ||
| $ docker network create my_network | ||
| $ tesseract serve "my-tesseract:latest" --network my_network --network-alias my-tesseract --port 8000 | ||
| ``` |
There was a problem hiding this comment.
Shouldn't we patch in auto-generation of networks right away? Otherwise we'll end up refactoring this part of the docs again once we do.
|
#544 tackles automatic network creation. Let's revisit the doc changes after, as you suggested @dionhaefner. |
…it does not exist (#544) #### Relevant issue or PR #530 documents how to use the `--network` option and needs updating once this PR is merged. #### Description of changes When `--network <name>` is passed to `tesseract serve` or `tesseract run` and no network with that name exists, we now automatically create it instead of failing with a Docker error. #### Testing done Tested that multi-Tesseract hello world example works without explicit network creation. --------- Co-authored-by: Dion Häfner <dion.haefner@simulation.science>
|
Done, @zmheiko do your thang |
2 participants
This addresses the lack of documentation around network usage and some of its pitfalls.
Relevant issue or PR
This acts as a stopgap for #410. Moving forward, more tooling around network usage is needed.
Description of changes
Add documentation