{"id":13668037,"url":"https://github.com/scaleway/image-tools","last_synced_at":"2025-12-30T00:20:04.840Z","repository":{"id":22477314,"uuid":"25816353","full_name":"scaleway/image-tools","owner":"scaleway","description":":nut_and_bolt: Scripts used to create Images on Scaleway - https://github.com/scaleway-community","archived":false,"fork":false,"pushed_at":"2024-04-11T17:20:28.000Z","size":463,"stargazers_count":117,"open_issues_count":38,"forks_count":36,"subscribers_count":27,"default_branch":"master","last_synced_at":"2025-03-22T15:49:54.360Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://github.com/scaleway-community","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/scaleway.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2014-10-27T11:47:14.000Z","updated_at":"2024-01-31T00:36:41.000Z","dependencies_parsed_at":"2024-08-02T07:02:08.297Z","dependency_job_id":null,"html_url":"https://github.com/scaleway/image-tools","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scaleway%2Fimage-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scaleway%2Fimage-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scaleway%2Fimage-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scaleway%2Fimage-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/scaleway","download_url":"https://codeload.github.com/scaleway/image-tools/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251035279,"owners_count":21526338,"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":[],"created_at":"2024-08-02T07:01:01.278Z","updated_at":"2025-12-30T00:20:04.810Z","avatar_url":"https://github.com/scaleway.png","language":"Shell","funding_links":[],"categories":["Shell"],"sub_categories":[],"readme":"# Scaleway Image Toolbox\n\nThis repository contains the tools, documentation, examples and content for creating images on [Scaleway](https://www.scaleway.com/).\n\n\n## Distribution images \u0026 Instant Apps\n\nOfficial Scaleway images are found as git repositories on Github, in two organizations:\n* [scaleway](https://github.com/scaleway), which focuses on bases images and distributions, with names prefixed by \"image-\"\n* [scaleway-community](https://github.com/scaleway-community) is dedicated to Instant Apps and ready-to-use images, where names are prefixed with \"scaleway-\".\n\nYour contributions are welcome !\n\nYour custom images can be anywhere, though, they don't even need to be in repositories.\n\n\n## Getting started\n\n### Simple images\n\nOn Scaleway, images are created by tagging an existing snapshot appropriately. This can be done with the [`scw` CLI tool](https://github.com/scaleway/scaleway-cli) (or alternatively, using the [console](https://cloud.scaleway.com) or directly through [the API](https://developer.scaleway.com)):\n\n```\n# Using the scw tool -- this assumes you've already set it up.\n# Create a snapshot first:\n$ scw commit -v 1 my-server my-snapshot\nf3af311c-53f7-4f5d-9252-0bf69f017269\n\n# Now make an image out of it:\n$ scw tag --arch=x86_64 --bootscript=\"mainline 4.14\"  my-snapshot my-image\na601dbac-08cb-4af3-9ff6-73b7e8dfd34f\n\n$ scw images\nREPOSITORY           TAG                 IMAGE ID            CREATED             REGION              ARCH\nuser/my-image        latest              a601dbac            5 seconds           [     par1]         [x86_64]\n---- snipping all stock images 8\u003c ----\n```\n\n### Docker-based images\n\nUsing the tools contained in this repository, it is possible to create Scaleway images from Docker images. At its core, this process uses the tools we explored above and is pretty straightforward to use: \n  1. Clone this repository and the repository of the image (if there is one) on a Scaleway instance\n  2. In your terminal, navigate to the image-tools directory, and type `make IMAGE_DIR=\u003cthe image's directory\u003e scaleway_image`\n  3. ???\n  4. Profit !\n\nAs a first example, let's simply rebuild our Ubuntu Xenial image without changing anything. Note that this is not needed to build your own Docker-based images, and is shown here only for demonstration purposes.\n\n[![asciicast](https://asciinema.org/a/foiok7e9gWnyqKK6HbWQIaAQz.png)](https://asciinema.org/a/foiok7e9gWnyqKK6HbWQIaAQz)\n\nNow that we've had a first taste, let's create a custom image based on Scaleway's Ubuntu image:\n\n[![asciicast](https://asciinema.org/a/qRVW81Ciqd1eeoki3Enyn3X7e.png)](https://asciinema.org/a/qRVW81Ciqd1eeoki3Enyn3X7e)\n\nTo recap, here's what's needed for a custom Docker-based image:\n  - A Dockerfile with an `ARCH` buildarg, based on any Docker image as long as the `FROM` chain can be traced back to one of Scaleway's official images on the Dockerhub: this is needed so that your custom image will ship with the needed tools, configuration and initialization scripts.\n  - An env.mk file, containing metadata for the builder tool. It must be valid makefile syntax and will be included at the beginning of the build process. It must at least set the following variables: `IMAGE_NAME`, `IMAGE_VERSION` and `IMAGE_TITLE` but can also set other information, such as authorship, or extra buildargs for Docker with `BUILD_ARGS`.\n  \nAll the rest is up to you and your creativity ! You can, for example, upload your images to the Dockerhub and start using them as bases for other images.\n\nAfter building, the image and associated snapshots will be available for use with your account. Note that introducing name conflicts will force you to use the ids to interact with the images through the CLI.\n\n\n## Diving below the surface\n\nThis section mainly deals with explaining with what happens during the build process. Reading it is not required to be able to create images.\n\nAs explained above, images are created by tagging a snapshot. Snapshots capture the state of a server's volume at a certain point in time. The simplicity of this step is what makes it versatile: as long as you can somehow get a server to boot and populate one of its volume with some data, you can create a Scaleway Image.\n\nFrom there, images can be built in many ways. An example would be to use a server with two volumes, using the first as a system volume and populating the second one as needed (parted, mkfs, debootstrap, pacstrap, etc...) before taking a snapshot of it. Snapshots can only be created when the server is off, though, so you would need to stop it. This can get a bit complicated when you need to build images repeatedly, and requires you to have a dedicated server for the pupose of image creation, so it might be a bit unpractical. \n\n### The build initrd\n\nTo make things easier, we created a lightweight tool for the purpose of image creation in the form of a [special initrd](https://github.com/scaleway/initrd/tree/master/build). An initrd, short for **initial ramdisk**, is a minimal root filesystem that is loaded in memory and mounted from there. In its classic form, an initrd is used to setup the core components of the system and finding the real root filesystem, before surrendering execution to the OS' *init*.\n\nThis build initrd is a bit different, as it does not aim to hook into a complete boot and will never call init. It is a intended to be used via a remote boot through preset bootscripts, which are specifications of a kernel + initrd that we feed into [IPXE](http://ipxe.org), the network boot firmware. A server can be assigned a bootscript at creation. The ids of the build bootscripts for different architectures can be found in the `bootscript_ids` file at the root of this project. It can also be accessed with the name \"Image creation bootscript\".\n\nDetailed information can be found in the initrd's repository, but let's recap its features broadly.\n\nThe build initrd offers different methods for building images, which are a collection of scripts. After setting up the network and retrieving metadata, it will use the method specified in the `build_method` parameter given through the metadata environment. Each method requires specific arguments.\n\nThe main method used by the image-tools suite is `from-rootfs`, which will retrieve a tarred rootfs from a given location and will apply it to the volume after setting up partitions (Linux, EFI) and their associated filesystem (ext4, fat32). GRUB EFI will then be installed to the partition. For example:\n\n```\n$ scw create --bootscript=\"image creation\" --env=\"build_method=from-rootfs rootfs_url=\u003curl of the rootfs.tar\u003e\" 50G\n```\n\nOther build methods also exist:\n  - `from-qcow2`, which will copy a qcow2 file's content to the device,\n  - `unpartitioned-from-rootfs` which will skip the partitions and EFI setup and use the raw device with an ext4 filesystem. Obviously, these images can only be booted remotely.\n  \nFinally, the build initrd will signal the completion of its job by opening a port given to it through the `signal_build_done_port` parameter, or 22 by default.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscaleway%2Fimage-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fscaleway%2Fimage-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscaleway%2Fimage-tools/lists"}