- Notifications
You must be signed in to change notification settings - Fork4
Develop from any device with a browser.
License
pojntfx/pojde
Folders and files
Name | Name | Last commit message | Last commit date | |
---|---|---|---|---|
Repository files navigation
Develop from any device with a browser.
pojde is a distributed multi-tenant development environment with web access to all components.
It strives to be ...
- Open: Free/libre and open source software under the AGPL-3.0 license
- Versatile: Supports multiple isolated instances on one host (for multi-user and/or multi-usecase support)
- Fast: Minimal base image with optional modules for languages and tools
- Portable: Runs on both Intel/AMD and ARM and requires Docker as the only dependency
- Lean: Built on projects likecode-server andJupyterLab
With pojde, you candevelop from any device with a browser!
To installpojdectl
, the management tool for pojde, run the following:
$ curl https://raw.githubusercontent.com/pojntfx/pojde/main/bin/pojdectl| bash -s -- upgrade-pojdectl
Works on Linux, macOS and Windows (WSL2). Now, continue toUsage to create your first instance.
I've created a brief YouTube video which guides you through the process:
If you prefer the instructions in written form, continue reading.
pojde supports running many isolated instances on a host, where the host can be your local machine, a cloud server or even a Raspberry Pi. Before you continue to the next step, please install eitherDocker orPodman on the host that you wish to run the instance on. Please note:
- If you have CGroups V2 enabled on your system (i.e. if you're using Fedora), please check out theDocker, Podman and CGroups V2 FAQ first.
- Host systems using systemd have the best support, but on systems which don't support it (i.e. Docker on macOS or WSL), pojde falls back to using OpenRC instead.
To create your first instance, usepojdectl apply
:
$ pojdectl apply my-first-instance 5000# Append `-n root@your-ip:ssh-port` to create the instance on a remote host instead
Now follow the instructions.pojdectl apply
will ask you to download the CA certificate to your system, which you should do when creating the first instance; future instances will share this certificate. You can also get the certificate at any later point usingpojdectl get-ca-cert
.
To trust the CA certificate, follow the videos we've created for you:
- Trusting self-signed CA certificates (system-wide on Fedora)
- Trusting self-signed SSL certificates (Chrome on Linux)
- Trusting self-signed SSL certificates (Chrome on macOS)
- Trusting self signed SSL certificates (Chrome on Windows)
Note that you'll have toselect the CA certificate you've downloaded in the step before, not download the certificate as described in the videos.
Once you've done so, confirm that everything went well by listing your instances withpojdectl list
:
$ pojdectl list# Append `-n root@your-ip:ssh-port` to list the instances on a remote host insteadNAME STATUS PORTSmy-first-instance running 5000-5005
As you can see, our first instance (my-first-instance
) is running and has exposed ports5000
through5005
. This port range has been selected when we ranpojdectl apply
above.
You can now access the services you've enabled (replacelocalhost
with your remote host's IP or domain if you deployed to a remote host):
Icon | Service | Address | Description |
---|---|---|---|
Cockpit | https://localhost:5000/ | General management interface | |
![]() | code-server | https://localhost:5001/ | VSCode in the browser |
![]() | ttyd | https://localhost:5002/ | Shell access from the browser |
![]() | noVNC | https://localhost:5003/ | Graphical access from the browser |
JupyterLab | https://localhost:5004/ | Interactive development environment |
If you can't access the services from outsidelocalhost
, make sure to open the ports on your firewall.
Additionally, there is a SSH server running on port5005
which you can use to forward ports from the instance withpojdectl forward
:
$ pojdectl forwardlocal my-first-instance 127.0.0.1:4200:127.0.0.1:1234 127.0.0.1:4201:127.0.0.1:1235# Append `-n root@your-ip:ssh-port` to also forward from the remote host to the local host
This, for example, forwards remote port1234
in the instance to local port4200
and remote port1235
to local port4201
.
You can also forward ports to the instance:
$ pojdectl forward remote my-first-instance 127.0.0.1:6969:127.0.0.1:6969# Append `-n root@your-ip:ssh-port` to also forward from the local host to the remote host
🚀 That's it! We hope you enjoy using pojde. Please be sure to also check out theUpdates andFAQ sections to keep your pojde setup up to date.
pojde is based on a minimal base image; additional functionality can be added by enabling any of the following modules when runningpojdectl apply
:
- Vim: Vim and the VSCodeVim extension
- QEMU, Docker and Kubernetes:
kubectl
,helm
,k9s
,skaffold
,k3d
and more DevOps tools - Technical Documentation:
pandoc
,plantuml
,gnuplot
, media, Office, PDF and Markdown/LaTeX support for VSCode - Full LaTeX Support: Full TeX Live installation
- Web Development: Protobuf, GraphQL, OpenAPI, browser debugging and more VSCode extensions
- Common VSCode Extensions: Prettier, GitLens, Git Graph and test explorer VSCode extensions
- Common CLIs:
tmux
,jq
,htop
etc. - Networking: Wireshark,
nmap
,iperf3
etc. - Browsers and Mail (TUI):
lynx
,links
,aerc
etc. - Browsers and Mail (GUI): Chromium, Firefox, GNOME Web and Thunderbird
- Multimedia:
ffmpeg
, Handbrake,youtube-dl
etc.
$ pojdectl --helppojdectl is the management toolfor pojde.Global Flags:[-n]ode<user@host:port> Remote host to execute on. If not specified, execute locally.Modification Commands:apply<name><startPort> Create or upgrade an instance. [-f]orce Skip confirmation prompts. [-u]pgrade Pull latest image. [-r]ecreate Re-create the container. [-i]solate Block Docker daemon access. [-p]rivileged Runin privileged mode.remove [name...] Remove instances(s). [-f]orce Skip confirmation prompts. [-c]ustomization Remove customizations. [-p]references Remove preferences. [-s]ecurity Remove CA. [-u]ser data Remove user data. [-t]ransfer Remove transfer data. [-d]eb cache Remove .deb cache. [-a]ll Remove everything.list List all instances.Lifecycle Commands:start [name...] Start instance(s).stop [name...] Stop instance(s).restart [name...] Restart instance(s).Utility Commands:logs<name> Get the logs of an instance.enter<name> Get a shellin an instance.forward<name><local|remote> [lhost:lport:rhost:rport...] Forward port(s) to or from an instance.Miscellaneous Commands:upgrade-pojdectl Upgrade this tool.get-ca-cert [-p]rint Get the CA cert.reset-ca [-f]orce Reset the CA.For more information, please visit https://github.com/pojntfx/pojde#Usage.
To contribute, please use theGitHub flow and follow ourCode of Conduct.
To build and start a development version of pojde locally, run the following:
$ git clone https://github.com/pojntfx/pojde.git$cd pojde$ make build$ ./bin/pojdectl apply my-first-instance 5000 -f -r
You should now have the pojde services running onhttp://localhost:5000/ throughhttp://localhost:5004/ (seeAccessing the Services). Whenever you change something in the source code, runmake build
and./bin/pojdectl apply my-first-instance 5000 -f -r
again, which will recompile and restart the services.
Have any questions or need help? Chat with uson Matrix!
pojdectl
includes a self-update tool, which you can invoke by running the following:
$ pojdectl upgrade-pojdectl
Updating an instance (to get the latest pojde version) and changing an instance's configuration are both done using thepojdectl apply
command.
To for example update the instance created inUsage or to change it's configuration, installed modules etc., run the following and follow the instructions:
$ pojdectl apply my-first-instance 5000 -f -r -u# Append `-n root@your-ip:ssh-port` to upgrade the instance on a remote host instead
There are multiple update and configuration strategies available; seeReference for more options.
The following combinations are known to work:
- Podman and CGroups V2
- Docker and CGroups V1
Using Docker and CGroups V2 together on a systemd-based host does not work, as running systemd inside the container is not yet supported properly using this configuration. If you are using CGroups V2, i.e. if you're on Fedora, please use Podman. Alternatively, you can also switch to CGroups V1 and use Docker:
$ sudo grubby --update-kernel=ALL --args="systemd.unified_cgroup_hierarchy=0"$ sudo reboot
Thanks to thepojde-docker-env
script, mounting Docker volumes from within an instance is supported:
pojntfx@5d084b2bf2ca:~$ pojde-docker-env# Run this in the instance, using i.e. `ttyd` or code-server's terminalpojntfx@5d084b2bf2ca:/var/lib/docker/volumes/pojde-my-first-instance-home-user/_data/pojntfx$# You can now use i.e. `docker run -v` in this shell!
You can also block Docker daemon access completely by specifiying the-i
flag; seeReference for more information.
There are many options available to transfer files; you can for example usescp
, another "traditional" option or use one of the following inbuilt ones.
A transfer folder is automatically created for even easier exchange of data between the host system and the instance; this folder is mounted into~/Documents
in the instance and available at~/Documents/pojde/your-instance-name
on the host system.
WebWormhole (available asww
) is pre-installed in every instance; it allows you to exchange files globally by using WebRTC. Find out more over at theWebWormhole GitHub repo.
pojde (c) 2021 Felicitas Pojtinger and contributors
SPDX-License-Identifier: AGPL-3.0