{"id":20095946,"url":"https://github.com/pirafrank/workspace","last_synced_at":"2026-01-05T07:17:47.783Z","repository":{"id":38281839,"uuid":"153930241","full_name":"pirafrank/workspace","owner":"pirafrank","description":"A workspace-in-a-container project powered by my https://github.com/pirafrank/dotfiles","archived":false,"fork":false,"pushed_at":"2024-09-24T08:24:31.000Z","size":624,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-03T11:06:52.788Z","etag":null,"topics":["cli","docker","dotfiles","git","linux","macos","prezto","shell","tmux","ubuntu","vimrc","workspace","workspaces","zsh"],"latest_commit_sha":null,"homepage":"https://hub.docker.com/r/pirafrank/workspace","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pirafrank.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-10-20T17:23:29.000Z","updated_at":"2024-08-05T17:07:43.000Z","dependencies_parsed_at":"2024-08-05T19:29:39.288Z","dependency_job_id":null,"html_url":"https://github.com/pirafrank/workspace","commit_stats":null,"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pirafrank%2Fworkspace","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pirafrank%2Fworkspace/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pirafrank%2Fworkspace/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pirafrank%2Fworkspace/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pirafrank","download_url":"https://codeload.github.com/pirafrank/workspace/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252628902,"owners_count":21779101,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","docker","dotfiles","git","linux","macos","prezto","shell","tmux","ubuntu","vimrc","workspace","workspaces","zsh"],"created_at":"2024-11-13T16:57:07.231Z","updated_at":"2026-01-05T07:17:47.712Z","avatar_url":"https://github.com/pirafrank.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Workspace\n\n[![Twitter](https://img.shields.io/twitter/url/https/twitter.com/pirafrank.svg?style=social\u0026label=Follow%20%40pirafrank)](https://twitter.com/pirafrank)\n[![Docker build](https://github.com/pirafrank/workspace/actions/workflows/docker.yml/badge.svg)](https://github.com/pirafrank/workspace/actions/workflows/docker.yml)\n[![Linux](https://github.com/pirafrank/workspace/actions/workflows/full_setup_testing.yml/badge.svg)](https://github.com/pirafrank/workspace/actions/workflows/full_setup_testing.yml)\n[![macOS](https://github.com/pirafrank/workspace/actions/workflows/macos_testing.yml/badge.svg)](https://github.com/pirafrank/workspace/actions/workflows/macos_testing.yml)\n[![docker_pulls](https://img.shields.io/docker/pulls/pirafrank/workspace.svg)](https://hub.docker.com/repository/docker/pirafrank/workspace)\n[![GitHub tag](https://img.shields.io/github/tag/pirafrank/workspace?include_prereleases=\u0026sort=semver\u0026color=blue)](https://github.com/pirafrank/workspace/releases/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/pirafrank/workspace/blob/main/LICENSE.md)\n\nA workspace-in-a-container project.\n\n`workspace` is a portable environment in a Docker container, powered by my work and personal dotfiles setup. You can test it straight away:\n\n```sh\ndocker run -it --name=workspace pirafrank/workspace:bundle\n```\n\n## Before we start\n\n**Important : Renamed repository!**\n\nThis repository is was previously named `dotfiles` and has been renamed to `workspace`. Dotfiles that once were part of this repo have moved [to their own](https://github.com/pirafrank/dotfiles). Now they are here as a submodule.\n\nI went this way to have the chance to further evolve the workspace project away from dotfiles, keeping both consistent commit history and releases made until today. On the other hand, the `dotfiles` repo has a rewritten commit history.\n\n## What's included\n\n- Ubuntu 20.04-based\n- `zsh` + zprezto as default shell\n- [dotfiles](https://github.com/pirafrank/dotfiles)\n- vim as IDE\n- cloud clients and tools\n- Java + mvn\n- node.js\n- Python 3\n- Golang\n- Rust\n- Ruby\n- various utils\n- optional Docker CLI client\n- support for different env versions\n- ...and more.\n\n## Supported platforms\n\nDocker images work anywhere Docker images run, from your PC to Kubernetes, to CaaS services.\n\nWhile almost all scripts and configurations in this repo will also work on non-Debian distros, `setup.sh` script in root is designed for the Debian-based ones. That said, the only differences shoud rely only on a few package and binary names.\n\nmacOS + macports is partially supported. I try to make `workspaces` and `setups` scripts work there too, yet macOS is not my daily driver anymore and the Apple Silicon transition adds spice to the receipe.\n\n## Usage\n\nChoose one of the options below:\n\n1. run the containerized workspace (Docker required)\n2. run the full `setup.sh` script on a vanilla environment (e.g. a new VPS install)\n3. setup specific features (Java+mvn, node.js, etc.) using the scripts in `setups` and `workspaces` dirs. Those scripts are also used to build the workspace Docker images.\n\n### 1. Workspace-in-a-container\n\nYou can run the workspace-in-a-container in many occasions.\n\n- easy and fast setup of CLI environment e.g. in a VPS\n- Works in CaaS services like Azure Container Instances and [Blink Build](scenarios/Blink%20Build/README.md)\n- great for already-configure, fast, ephimeral dev environment\n- you name it...\n\nPlease check the workspace-in-a-container '[Usage scenarios](#usage-scenarios)' section for further info.\n\n### 2. Full setup\n\n*Debian-based distros only.*\n\nA full setup involves programs installation of programs, their dependencies, download of dotfiles and creation of symlinks. It is meant to setup a vanilla environment. I keep `setup.sh` aligned with the `Dockerfile` used to build the Docker workspace baseimage. The setup comes in two flavors, with and without user creation:\n\n```sh\ncurl -sSL https://github.com/pirafrank/workspace/raw/main/create_user.sh -o create_user.sh \u0026\u0026 chmod +x create_user.sh\ncurl -sSL https://github.com/pirafrank/workspace/raw/main/setup.sh -o setup.sh \u0026\u0026 chmod +x setup.sh\n./create_user.sh\n./setup.sh\n```\n\nRun the one that best fits your needs. Remember to always check the content of scripts you're about to execute before running them!\n\n### 3. Partial setup\n\nSetup scripts in `setups` and `workspaces` dirs are meant to be executed manually on Linux or macOS, or to build Docker Image workspaces (read below). They assume `~/dotfiles` exists. If you have dotfiles in another dir, please symlink it to `~/dotfiles`.\n\nCore setup uses zsh and zprezto. Files for oh-my-zsh config are available, but I don't use/update them anymore.\n\n### Further notes\n\n`~/.zsh_custom` is automatically sourced if it exists, and `~/bin2` is automatically added to `$PATH`. Both are not part of the repo and can be used to add your-own or machine-specific customizations and other executables.\n\nThat's all, there is no real how-to actually. For more info just look at the code.\n\n## A workspace-in-a-container\n\nThe main focus is to make Workspace a great workspace-in-a-container setup.\n\n### Available Docker images\n\nThe aim is to create a disposable development environment taking advantage of Docker. Images are publicly available on [Docker Hub](https://hub.docker.com/r/pirafrank/workspace) in various flavors. They are:\n\n- `pirafrank/workspace`: base image on which the others are based on. It contains dotfiles, various CLI utils and shell setup\n- `pirafrank/workspace:bundle`: bundle of the ones below. Use `workspace_version` inside the container to know about what's bundled.\n\nDockerfiles available to build:\n\n- `pirafrank/workspace:java`: Java + `mvn`\n- `pirafrank/workspace:node`: `nvm` + node.js\n- `pirafrank/workspace:python3`: `pyenv` + Python 3\n- `pirafrank/workspace:ruby`: `rvm` + Ruby\n- `pirafrank/workspace:rust`: latest Rust version and its toolchain\n- `pirafrank/workspace:go`: Golang workspace\n\nAll workspaces setups are in userspace.\n\n### Versioning\n\nThe following apply:\n\n- Docker image builds are made from `main` branch only. Builds are triggered only if changes are made to source files (e.g. it skips changes to pipeline files, README, etc.).\n- Only after a successful pipeline run, builds are pushed to docker registries and lightweight tags are added to the repository. Those tags have format: `YYYYMMDD.CommitHash`.\n- After a meaniful set of changes are added to repository, I tag one of those lightweight-tagged commits with a signed annotated one using semantic versioning format.\n- By the way, although versioning plays its part in pulling a specific version, `latest` and `bundle` tags are meant to be used as the latest stable images.\n\n### OpenSSH Server\n\nWorkspace images now ship with openssh-server, so you can deploy your workspace on a CaaS provider and SSH to it.\n\nBy default the openssh-server won't start and an interactive shell will launch, this means that if you won't start the workspace from an interactive shell it will exit immediately!\n\nIf you deploy on a CaaS and want to leverage openssh-server, just pass these two ENV VARs upon container start:\n\n- `SSH_SERVER`, any value is ok (e.g. 'true'), just don't leave it null;\n- `SSH_PUBKEYS`, it holds the pubkey you want to use to connect via SSH (only one pubkey supported atm).\n\nIt listens to `0.0.0.0:2222`.\n\nFor example:\n\n```sh\ndocker run -it --rm \\\n    -p \"2222:2222\" \\\n    -e SSH_SERVER=true -e SSH_PUBKEYS=\"ssh-ed25519 AAAA... francesco@work\" \\\n    pirafrank/workspace:latest\n```\n\nif you have multiple SSH pub keys:\n\n```sh\n# from file\nexport SSHKEYS=`cat file_with_many_keys`\n# from URL\nexport SSHKEYS=`curl -sSL some.url/with/keys/sshkeys`\n# then in command above\n... -e SSH_SERVER=true -e SSH_PUBKEYS=\"${SSHKEYS}\" ...\n```\n\nor via run script:\n\n```sh\nbash run-workspace.sh latest '--rm -e SSH_SERVER=true -e SSH_PUBKEYS=\"ssh-ed25519 AAAA... francesco@work\"'\n```\n\nCheck `pre_start.zsh` and `start.sh` scripts for further info.\n\n## Usage scenarios\n\nYou can run your workspace in many ways. Check the examples in `scenarios` [dir](scenarios/).\n\n### Docker Compose\n\nSimple use case start to run it locally, e.g. you need tools and don't want to install them on your PC.\n\nPleas check the readme [here](scenarios/docker-compose/README.md).\n\n### You own Kubernetes\n\nGeneral purpose, openssh-server is a great helper here.\n\nFor the sake of brevity, please check files in the `scenarios/k8s` [dir](scenarios/k8s/).\n\n### Azure Container Instances\n\nAzure Container Instances provide a great environment to run workspace on-the-go and start/stop when you need it.\n\nPlease check the full readme [here](scenarios/azure_container_instances/README.md).\n\n### AWS Fargate\n\n*Coming soon...*\n\n### Blink Build\n\n*Build* is a new service being built by the guys behind [Blink Shell](https://twitter.com/BlinkShell/), the best SSH and mosh client for iOS and iPadOS. It's [currently in beta](https://github.com/blinksh/blink/discussions/1698) and allows you to SSH into any container publicly available without taking care of the underlying infrastructure, network or firewall. And it's fully integrated in Blink Shell. [I have started tinkering](https://twitter.com/pirafrank/status/1423633599459471361) with it and I have to say it's a great match with my *workspace* for a portable dev environment!\n\nPlease check the full readme [here](scenarios/Blink%20Build/README.md).\n\n### devcontainer.json\n\n*Coming soon...*\n\n## Build and run your own\n\nBuild and run images on Docker locally.\n\n### Build an image\n\nRun `./build.sh all` to build all images.\n\nAdd anything you want to exec right before container launch to `pre_start.zsh`.\n\nYou can also change the commands executed at startup by editing the `start.sh` script.\n\n### Run an image\n\nUse `run_workspace.sh` to do so. Clone the repo or just download the script.\n\nThe script will default to `pirafrank/workspace` images, you just need to specify the tag name.\n\nFor example:\n\n```sh\n# to run the baseimage\n./run-workspace.sh latest\n# or to run the java11 one\n./run-workspace.sh java11\n# or to run it as a disposable container\n./run-workspace.sh java11 --rm\n# or to name it\n./run-workspace.sh java11 '--name somename --rm'\n```\n\n## License\n\nCode in this repo is given away for free, as-is and with NO WARRANTY as per the MIT license.\n\nBy the way, if something really blows your mind, I'll be happy if you get in touch with me. I always appreciated feedback!\n\nEnjoy!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpirafrank%2Fworkspace","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpirafrank%2Fworkspace","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpirafrank%2Fworkspace/lists"}