|
1 | | -# base-user-image template |
| 1 | +# java-user-image |
2 | 2 |
|
3 | | -This is a template repository for creating dedicated single-user server images |
4 | | -for Cal-ICOR Jupyterhubs. |
| 3 | +See this repository's |
| 4 | +[CONTRIBUTING.md](https://github.com/cal-icor/java-user-image/blob/main/CONTRIBUTING.md) |
| 5 | +for instructions. |
5 | 6 |
|
6 | | -## Overall workflow |
| 7 | +## Java installation details |
7 | 8 |
|
8 | | -The basic workflow for creating a new hub user image is as follows: |
| 9 | +This image has Java installed via the |
| 10 | +[Jupyter Java project](https://github.com/jupyter-java) project. The Java 17 |
| 11 | +kernel is provided by [JJava](https://dflib.org/jjava/docs/1.x/) and the |
| 12 | +runtime is [OpenJDK JRE 11.0.27](https://packages.ubuntu.com/jammy/openjdk-21-jre) |
| 13 | +and [OpenJDK](https://packages.ubuntu.com/jammy/openjdk-21-jdk). |
9 | 14 |
|
10 | | -1. Create a new repository using this one as a template. Be sure to set the |
11 | | - owner as `cal-icor`. |
| 15 | +``` |
| 16 | +$ java -version |
| 17 | +openjdk version "21.0.7" 2025-04-15 |
| 18 | +OpenJDK Runtime Environment (build 21.0.7+6-Ubuntu-0ubuntu122.04) |
| 19 | +OpenJDK 64-Bit Server VM (build 21.0.7+6-Ubuntu-0ubuntu122.04, mixed mode, sharing) |
| 20 | +$ javac -version |
| 21 | +javac 21.0.7 |
| 22 | +``` |
12 | 23 |
|
13 | | -2. In the new repo, set the appropriate values in the Actions repository |
14 | | - variables for `HUB` (name of the hub) and `IMAGE` (relative path to the |
15 | | - image in ECR). |
| 24 | +## Building the image locally |
16 | 25 |
|
17 | | -3. Give the new repo access to the `cal-icor` organization-level |
18 | | - secrets: `GAR_SECRET_KEY`, `GCP_PROJECT_ID` and |
19 | | - `IMAGE_BUILDER_CREATE_PR`. |
| 26 | +You should use [repo2docker](https://repo2docker.readthedocs.io/en/latest/) to build and use/test the image on your own device before you push and create a PR. It's better (and typically faster) to do this first before using CI/CD. There's no need to waste Github Action minutes to test build images when you can do this on your own device! |
20 | 27 |
|
21 | | -4. Fork that repository to create your image repository. |
| 28 | +Run `repo2docker` from inside the cloned image repo. To run on a linux/WSL2 linux shell: |
| 29 | +``` |
| 30 | +repo2docker . # <--- the path to the repo |
| 31 | +``` |
22 | 32 |
|
23 | | -5. Configure your Hub to use this new image by modifying that deployment's |
24 | | - `hubploy.yaml` and add the parent repo's git information to |
25 | | - [`repos.txt`](https://github.com/cal-icor/cal-icor-hubs/blob/staging/configs/repos.txt) |
| 33 | +If you are using an ARM CPU (Apple M* silicon), you will need to run `jupyter-repo2docker` with the following arguments: |
26 | 34 |
|
27 | | -6. Customize the image by editing `repo2docker` configuration files in your |
28 | | - fork of the image repository, and then open a pull request to merge these |
29 | | - changes to the `main` branch of the parent repo in the |
30 | | - `cal-icor` organization. |
| 35 | +``` |
| 36 | +jupyter-repo2docker --user-id=1000 --user-name=jovyan \ |
| 37 | + --Repo2Docker.platform=linux/amd64 \ |
| 38 | + --target-repo-dir=/home/jovyan/.cache \ |
| 39 | + -e PLAYWRIGHT_BROWSERS_PATH=/srv/conda \ |
| 40 | + . # <--- the path to the repo |
| 41 | +``` |
31 | 42 |
|
32 | | -These steps are just a summary, and much more detailed instructions are |
33 | | -[located here](https://docs.datahub.berkeley.edu/admins/howto/new-image.html). |
34 | | - |
35 | | -In addition, we also provide a template for a simplified `README.md` |
36 | | -[here](https://github.com/cal-icor/cal-icor-hubs/blob/main/README-template.md). |
37 | | - |
38 | | -### Modifying the new image |
39 | | - |
40 | | -The process to modify and push an image to the Google Artifact Registry via the |
41 | | -CI/CD pipeline is located in the [contribution guide](CONTRIBUTING.md) |
42 | | - |
43 | | -### Moving an existing image into the `cal-icor` organization |
44 | | - |
45 | | -If you have an existing image repository, and would like to bring it in to the |
46 | | -`cal-icor` organization and retain the `git` history, please refer |
47 | | -to our documentation :arrow_right: |
48 | | -https://docs.datahub.berkeley.edu/admins/howto/transition-image.html |
49 | | - |
50 | | -Our documentation is based on helpful guide put together by 2i2c :arrow_right: |
51 | | -https://infrastructure.2i2c.org/howto/update-env/#split-up-an-image-for-use-with-the-repo2docker-action |
52 | | - |
53 | | -## About this template repository |
54 | | - |
55 | | -This template repository uses the |
56 | | -[jupyterhub/repo2docker-action](https://github.com/jupyterhub/repo2docker-action) |
57 | | -to build a Docker image using the contents of this repo, and pushes it to our |
58 | | -[Google Artifact Registry](https://cloud.google.com/artifact-registry) when |
59 | | -a pull request is merged to `main`. |
60 | | - |
61 | | -### The environment |
62 | | - |
63 | | -The repo provides a default `environment.yml` conda configuration file for |
64 | | -`repo2docker` to use to define and build a single-user server image. This file |
65 | | -is used to define the python packages that will be installed during the image |
66 | | -build process, either via `conda` or `pip`. |
67 | | - |
68 | | -**Note:** |
69 | | -A complete list of configuration files that can be added to the |
70 | | -repository and used by `repo2docker` to build the Docker image can be found in |
71 | | -the [repo2docker documentation](https://repo2docker.readthedocs.io/en/latest/config_files.html#configuration-files). |
72 | | - |
73 | | -### Making changes to a single user server image |
74 | | - |
75 | | -Once you've created the new image repo from this template, please refer to |
76 | | -[the contribution instructions](CONTRIBUTING.md) located in the repo for |
77 | | -detailed instructions. |
78 | | - |
79 | | -### The GitHub Action workflows |
80 | | - |
81 | | -This template repository provides GitHub Action workflows that can build |
82 | | -and push the image to Google Artifact Repository when configured, and push a |
83 | | -commit to the [Cal-ICOR Jupyterhub repo](https://github.com/cal-icor/cal-icor-hubs) |
84 | | -repository that modifies `hubploy.yaml` for any hubs using this image with the |
85 | | -new SHA tag. |
86 | | - |
87 | | -#### 1. Build and test container image :arrow_right: [test.yaml](https://github.com/cal-icor/base-user-image/blob/main/.github/workflows/build-test-image.yaml) |
88 | | - |
89 | | -This workflow is triggered when a pull request is opened against the default |
90 | | -branch (`main`). During PR builds, the image is **only** built and **not** |
91 | | -pushed to the Google Artifact Registry. |
92 | | - |
93 | | -Please note that the image will not be built for documentation changes |
94 | | -(markdown files or any graphic images in the `images/` subdirectory). |
95 | | - |
96 | | -#### 2. YAML linting :arrow_right: [yaml-lint.yaml](https://github.com/cal-icor/base-user-image/blob/main/.github/workflows/yaml-lint.yaml) |
97 | | - |
98 | | -This workflow is triggered when a pull request is opened against the default |
99 | | -branch (`main`). It uses [yamllint](https://yamllint.readthedocs.io/en/stable/) |
100 | | -to check all yaml files in the repo for correctness. |
101 | | - |
102 | | -#### 3. **Temporarily disabled:** Test this PR on Binder Badge :arrow_right: [binder.yaml](https://github.com/cal-icor/base-user-image/blob/main/.github/workflows/binder.yaml.disable) |
103 | | - |
104 | | -Since our images are typically large and take > 10m to build, this means that |
105 | | -Binderhub builds will currently time out. |
106 | | - |
107 | | -#### 4. Build, test and push container image :arrow_right: [build-push-open-pr.yaml](https://github.com/cal-icor/base-user-image/blob/main/.github/workflows/build-push-create-pr.yaml) |
108 | | - |
109 | | -After a PR is merged to `main`, this workflow builds the image again, pushes it |
110 | | -to the Google Artifact Registry and then creates a commit that updates the image tag |
111 | | -for any hubs that use this image. That commit is then pushed to the |
112 | | -[Cal-ICOR Jupyterhub repo](https://github.com/cal-icor/cal-icor-hubs), and you will |
113 | | -then need to manually create a pull requests to merge and deploy the new image. |
| 43 | +If you just want to see if the image builds, but not automatically launch the server, add `--no-run` to the arguments (before the final `.`). |
0 commit comments