|
| 1 | +# Flake-based Docker Build Environment for Polar |
| 2 | + |
| 3 | +This repository provides secure, resilient, and repeatable build environments |
| 4 | +for Polar using NixOS and Docker. The setup ensures that the same process used |
| 5 | +for local development builds can also be utilized for CI/CD pipeline builds, |
| 6 | +providing consistency and isolation. |
| 7 | + |
| 8 | +## Prerequisites |
| 9 | + |
| 10 | +Before starting, ensure you have the following installed: |
| 11 | + |
| 12 | +- [Nix package manager](https://nixos.org/download.html) |
| 13 | +- [Docker](https://docs.docker.com/get-docker/) |
| 14 | + |
| 15 | +## Setup |
| 16 | + |
| 17 | +1. **Install Nix and enable it to use flakes:** |
| 18 | + Checkout the instructions at https://nix.dev/ on how you can do this. |
| 19 | + Chances are you can run the following command once you have nix installed to configure it |
| 20 | + ```sh |
| 21 | + printf 'experimental-features = nix-command flakes' > "$HOME/.config/nix/nix.conf" |
| 22 | + ``` |
| 23 | + |
| 24 | +## Building the Docker Images |
| 25 | +1. **Enter the project directory:** |
| 26 | + |
| 27 | + ```bash |
| 28 | + cd /path/to/your/project/dev-container |
| 29 | + ``` |
| 30 | + |
| 31 | +2. **Build one of the images using Nix:** |
| 32 | + |
| 33 | + ```bash |
| 34 | + # Builds a full rust development environment for the project |
| 35 | + nix build .#devContainer |
| 36 | + |
| 37 | + # build the CI/CD container for a more lean testing environment |
| 38 | + nix build .#ciContainer |
| 39 | + ``` |
| 40 | + |
| 41 | +3. **Load the Docker image:** |
| 42 | + |
| 43 | + ```bash |
| 44 | + docker load < result |
| 45 | + ``` |
| 46 | + |
| 47 | + The development image will be tagged as `polar-dev:latest`. To change the tag, |
| 48 | + use the Docker `tag` command specifying the new tag. |
| 49 | + |
| 50 | +## Running the Docker Container |
| 51 | + |
| 52 | +1. **Run the Docker containers with your project directory mounted:** |
| 53 | + ```bash |
| 54 | + docker run -it -v /path/to/your/project:/workspace -p 8080:8080 polar-dev:latest bash -c "/create-user.sh $(whoami) $(id -u) $(id -g)" |
| 55 | + ``` |
| 56 | + |
| 57 | + The create user command will set the user within the container and then |
| 58 | + drop into the fish shell. Replace `/path/to/your/project` with the path to |
| 59 | + your project directory. This command mounts your project directory into the |
| 60 | + container at the `/workspace` directory, allowing you to work on your |
| 61 | + project files within the container. |
| 62 | + |
| 63 | + The `-p 8080:8080` flag forwards port 8080 from the container to your local |
| 64 | + machine, allowing you to access services running inside the container, |
| 65 | + which can be removed if not using Code Server. |
| 66 | + |
| 67 | +## Running with VSCode Dev Containers |
| 68 | + |
| 69 | +This setup is compatible with the VSCode Dev Containers feature, allowing you |
| 70 | +to use Visual Studio Code as your IDE inside the Nix based container. |
| 71 | + |
| 72 | +1. **Open this project in Visual Studio Code.** |
| 73 | + |
| 74 | +2. **Install the Remote - Containers extension in VSCode.** |
| 75 | + |
| 76 | +3. **Open the command palette (`Ctrl+Shift+P` or `Cmd+Shift+P`) and select |
| 77 | + `Dev-containers: Reopen in Container`.** |
| 78 | + |
| 79 | + |
| 80 | +## Running Code Server |
| 81 | + |
| 82 | +> [!NOTE] |
| 83 | +> You cannot run Code Server from within a container if it is already running as a VSCode Dev Container. |
| 84 | + |
| 85 | +To run `Code Server` inside the Docker container and access it via a web browser: |
| 86 | + |
| 87 | +1. **Start the Docker container with port forwarding:** |
| 88 | + |
| 89 | + ```bash |
| 90 | + docker run -it -v /path/to/your/project:/workspace -p 8080:8080 polar-dev:latest bash -c "/create-user.sh $(whoami) $(id -u) $(id -g)" |
| 91 | + ``` |
| 92 | + |
| 93 | +> ![Note] |
| 94 | +> For Fish, please use the following command: |
| 95 | +> ```fish |
| 96 | +> set -xu USER_ID (id -u) && set -xu GROUP_ID (id -g) && docker run -it -v /path/to/your/project:/workspace -p 8080:8080 polar-dev:latest bash -c "/create-user.sh (whoami) $USER_ID $GROUP_ID" |
| 97 | +> ``` |
| 98 | + |
| 99 | + Replace `/path/to/your/project` with the path to your project directory. |
| 100 | + |
| 101 | + |
| 102 | +2. **Inside the container, start `Code Server`:** |
| 103 | + |
| 104 | + ```bash |
| 105 | + code_server |
| 106 | + ``` |
| 107 | + |
| 108 | +3. **Access `Code Server` by navigating to `http://localhost:8080` in your web browser.** |
| 109 | + |
| 110 | +4. [Optional if on a remote server] **Forward port via ssh:** |
| 111 | + |
| 112 | + ```bash |
| 113 | + ssh -L 8080:localhost:8080 user@remote-server |
| 114 | + ``` |
| 115 | + |
| 116 | + Replace `user` with your username and `remote-server` with the IP address |
| 117 | + or hostname of the remote server. This command forwards port 8080 from the |
| 118 | + remote server to your local machine, allowing you to access `Code Server` |
| 119 | + running on the remote server. |
| 120 | + |
| 121 | +### Why Use `Code Server` Over VSCode Dev Containers? |
| 122 | + |
| 123 | +- **Fewer Dependencies:** |
| 124 | + Running `Code Server` does not require installing the VSCode IDE on your |
| 125 | + local machine, reducing the number of dependencies needed to work on your |
| 126 | + project, to only a web browser and docker. |
| 127 | + |
| 128 | +- **Lightweight:** |
| 129 | + `Code Server` is a lightweight version of Visual Studio Code that can be |
| 130 | + run in a browser, making it more resource-efficient than running the full |
| 131 | + VSCode IDE. |
| 132 | + |
| 133 | +- **Remote Access:** |
| 134 | + `Code Server` can be accessed remotely, allowing you to work on your |
| 135 | + project from any device with a web browser and the ability to connect to |
| 136 | + the server. |
| 137 | + |
| 138 | +- **Consistency:** |
| 139 | + Using `Code Server` ensures that the development environment is consistent |
| 140 | + across different machines and setups, providing a seamless developer |
| 141 | + experience. |
| 142 | + |
| 143 | + |
| 144 | +## Benefits of Using Nix and Flakes |
| 145 | + |
| 146 | +**Security and Reproducibility:** |
| 147 | +Nix provides a highly reproducible build system by describing the entire build |
| 148 | +environment as code, ensuring that builds are consistent across different |
| 149 | +environments and over time. This reduces the "works on my machine" problems and |
| 150 | +enhances security by eliminating unpredictable states. Nix Flakes further |
| 151 | +secure the process by locking down dependency versions and providing an |
| 152 | +isolated, declarative approach to package management. |
| 153 | + |
| 154 | +**Compatibility:** |
| 155 | +The use of Nix Flakes makes this environment easily compatible with VSCode Dev |
| 156 | +Containers, ensuring a seamless developer experience across different machines |
| 157 | +and setups. |
| 158 | + |
| 159 | +**Efficiency:** |
| 160 | +The Nix-based environment is lightweight and efficient, by only installing the |
| 161 | +necessary dependencies for the build process, reducing the overall size and |
| 162 | +complexity of the build environment and speeding up the build process. |
| 163 | + |
| 164 | +## Notes on update_extensions.fish |
| 165 | +If you're tweaking the container for your development workflow, one nice thing |
| 166 | +to do is to adjust the set of available VS Code extensions in your container. |
| 167 | +Getting the full list of available extensions, by name and in the format that |
| 168 | +is required by the nix package is kind of a pain, so I automated the process. I |
| 169 | +don't think we want to store the data files in the repo, but if you run the |
| 170 | +script, you'll get a couple of package lists that have been formatted as nix |
| 171 | +attribute strings. These can be directly added to the flake's config for VS |
| 172 | +Code, just search for and copy/paste the ones you want. If you don't know what |
| 173 | +you want, it's still helpful to look for them initially in the marketplace in |
| 174 | +the app. |
0 commit comments