{"id":13599036,"url":"https://github.com/cvpaperchallenge/Ascender","last_synced_at":"2025-04-10T12:31:05.986Z","repository":{"id":38318929,"uuid":"466620310","full_name":"cvpaperchallenge/Ascender","owner":"cvpaperchallenge","description":"Accelerator of Scientific Development and Research. A project template developed by XCCV group of cvpaper.challenge.","archived":false,"fork":false,"pushed_at":"2025-02-01T23:43:51.000Z","size":932,"stargazers_count":410,"open_issues_count":4,"forks_count":25,"subscribers_count":6,"default_branch":"develop","last_synced_at":"2025-02-02T00:25:53.834Z","etag":null,"topics":["ascender","docker","python"],"latest_commit_sha":null,"homepage":"","language":"Dockerfile","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/cvpaperchallenge.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-03-06T02:53:50.000Z","updated_at":"2025-02-01T23:43:56.000Z","dependencies_parsed_at":"2024-01-14T04:41:12.823Z","dependency_job_id":"9704a790-9c64-4764-8b1b-325df1376ba8","html_url":"https://github.com/cvpaperchallenge/Ascender","commit_stats":null,"previous_names":[],"tags_count":5,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cvpaperchallenge%2FAscender","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cvpaperchallenge%2FAscender/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cvpaperchallenge%2FAscender/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cvpaperchallenge%2FAscender/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cvpaperchallenge","download_url":"https://codeload.github.com/cvpaperchallenge/Ascender/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248217126,"owners_count":21066633,"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":["ascender","docker","python"],"created_at":"2024-08-01T17:00:59.129Z","updated_at":"2025-04-10T12:31:05.679Z","avatar_url":"https://github.com/cvpaperchallenge.png","language":"Dockerfile","funding_links":[],"categories":["Dockerfile"],"sub_categories":[],"readme":"# Ascender\n\n![stable](https://img.shields.io/badge/stable-v0.2.0-blue)\n![python versions](https://img.shields.io/badge/python-3.8%20%7C%203.9%20%7C%203.10%20%7C%203.11%20%7C%203.12-blue)\n[![tests](https://github.com/cvpaperchallenge/Ascender/actions/workflows/lint-and-test.yaml/badge.svg)](https://github.com/cvpaperchallenge/Ascender/actions/workflows/lint-and-test.yaml)\n[![MIT License](https://img.shields.io/github/license/cvpaperchallenge/Ascender?color=green)](LICENSE)\n[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)\n[![Typing: mypy](https://img.shields.io/badge/typing-mypy-blue)](https://github.com/python/mypy)\n[![DOI](https://zenodo.org/badge/466620310.svg)](https://zenodo.org/badge/latestdoi/466620310)\n\n## What is Ascender?\n\nAscender (Accelerator of SCiENtific DEvelopment and Research) is a [GitHub repository template](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-template-repository) designed for research projects using Python. It incorporates several pre-implemented features to expedite development:\n\n- **Containerization**: Dependency minimization and code portability enhancement using [Docker](https://www.docker.com/).\n- **Virtual Environment / Package Management**: Development environment reproducibility ensured by [Poetry](https://python-poetry.org/).\n- **Coding Style**: Automatic code linting and formatting with [Ruff](https://docs.astral.sh/ruff/).\n- **Static Type Checking**: Early bug detection assisted by [Mypy](https://github.com/python/mypy).\n- **Testing**: Testing simplification achieved through [pytest](https://github.com/pytest-dev/pytest).\n- **Task Runner**: Simple task automation with [Poe the Poet](https://github.com/nat-n/poethepoet).\n- **GitHub Integration**: Integration features including [GitHub Actions workflows](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions), issue templates, and more.\n\nPlease also view [resources about Ascender (in Japanese)](https://cvpaperchallenge.github.io/Britannica/ascender/ja).\n\n## Project Organization\n\n```\n    ├── .github/               \u003c- GitHub settings.\n    │\n    ├── data/                  \u003c- Datasets.\n    │\n    ├── environments/          \u003c- Environment-specific configurations.\n    │\n    ├── models/                \u003c- Pretrained and serialized models.\n    │\n    ├── notebooks/             \u003c- Jupyter notebooks.\n    │\n    ├── outputs/               \u003c- Outputs.\n    │\n    ├── src/                   \u003c- Python Source code.\n    │\n    ├── tests/                 \u003c- Test code.\n    │\n    ├── .dockerignore\n    ├── .gitignore\n    ├── LICENSE\n    ├── poetry.lock            \u003c- Auto-generated lock file (do not edit manually).\n    ├── poetry.toml            \u003c- Poetry configuration.\n    ├── pyproject.toml         \u003c- Main project configuration file.\n    └── README.md              \u003c- Top-level README for developers.\n```\n\n## Prerequisites\n\n- [Docker](https://www.docker.com/)\n- [Docker Compose](https://github.com/docker/compose)\n- (Optional) [NVIDIA Container Toolkit (nvidia-docker2)](https://github.com/NVIDIA/nvidia-docker)\n\n\u003e \\[!Note\\]\n\u003e The example codes in the README.md are written for `Docker Compose v2`. However, Ascender is also compatible with `Docker Compose v1`. If you are using `Docker Compose v1`, simply replace `docker compose` with `docker-compose` in the example commands.\n\n## Prerequisites Installation\n\nThis section provides installation instructions for Ubuntu. If you have already installed the prerequisites, you may skip this section. For installations on other operating systems, please refer to the official documentation.\n\n- Docker and Docker Compose: [Install Docker Engine](https://docs.docker.com/engine/install/)\n- NVIDIA Container Toolkit (nvidia-docker2): [Installation Guide](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html#docker)\n\n### Install Docker and Docker Compose\n\n```bash\n# Set up the repository\n$ sudo apt update\n$ sudo apt install ca-certificates curl gnupg lsb-release\n$ sudo mkdir -p /etc/apt/keyrings\n$ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg\n$ echo \\\n  \"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \\\n  $(lsb_release -cs) stable\" | sudo tee /etc/apt/sources.list.d/docker.list \u003e /dev/null\n\n# Install Docker and Docker Compose\n$ sudo apt update\n$ sudo apt install docker-ce docker-ce-cli containerd.io docker-compose-plugin\n```\n\nIf `sudo docker run hello-world` works, the installation was successful.\n\n### (Optional) Install NVIDIA Container Toolkit\n\nTo use GPUs with Ascender, install the NVIDIA Container Toolkit as well. This toolkit has specific prerequisites, detailed in the [official documentation](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html#pre-requisites).\n\n```bash\n$ distribution=$(. /etc/os-release;echo $ID$VERSION_ID) \\\n      \u0026\u0026 curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg \\\n      \u0026\u0026 curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | \\\n            sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \\\n            sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list\n\n$ sudo apt update\n$ sudo apt install -y nvidia-docker2\n$ sudo systemctl restart docker\n```\n\nIf `sudo docker run --rm --gpus all nvidia/cuda:11.0.3-base nvidia-smi` works, the installation was successful.\n\n## Quick Start\n\nThis section outlines how to begin using Ascender. For more detailed information, please refer to [this slide (in Japanese)](https://cvpaperchallenge.github.io/Britannica/ascender/ja).\n\n### Create a GitHub Repository from Ascender\n\nTo start, you need to create your own GitHub repository from Ascender:\n\n- Visit the GitHub repository page of Ascender.\n- Click the [\"Use this template\"](https://github.com/cvpaperchallenge/Ascender/generate) button at the top right of the page.\n- Complete the form and click the \"Create repository from template\" button.\n\nYour new repository should now be set up in your GitHub account.\n\n### (Optional) Modify Names Used in the Template\n\nIn the Ascender template, names used in the system by default, such as those for Docker containers and bind-mounted volumes, are set to \"ascender.\" Particularly when using Ascender’s template to create and manage multiple containers, to avoid name conflicts between containers, it is necessary to change the container names for each project (refer also to the FAQ section \"Building multiple containers with Ascender’s template\").\n\nIf you want to change the default names used in the system, please modify the value of `PROJECT_NAME_ENV` in `environments/[cpu,gpu,ci]/.env`.\n\n### (Optional) Set Environment Variables for Development Within the Container\n\nDepending on the services, frameworks, and libraries used during development, it may be necessary to specify API keys, database hostnames, and passwords as environment variables. To use environment variables within the container, please follow the steps below.\n\n- Copy `environments/envs.env.sample` to create `environments/envs.env`\n\n- Edit `environments/envs.env` to set the environment variables you want to use inside the container\n\n- Add the `env_file` option to `environments/[cpu,gpu]/docker-compose.yaml`, and specify the path to `environments/envs.env` that was created above (by uncommenting the section that is commented out by default).\"\n\n  ```yaml\n  # env_file:       # \u003c- uncomment here\n  #   - ../envs.env # \u003c- uncomment here\n  ```\n\n\u003e \\[!Note\\]\n\u003e The `envs.env` file may contain sensitive information such as API keys and passwords and should not be version-controlled by Git. In Ascender, files named `*.env` are excluded from Git tracking by default, as they are listed in the `.gitignore` file.\n\n### Start Development\n\n```bash\n# Clone the repository\n$ git clone git@github.com:cvpaperchallenge/\u003cYOUR_REPO_NAME\u003e.git\n$ cd \u003cYOUR_REPO_NAME\u003e\n\n# Build the Docker image and run the container\n$ cd environments/gpu  # For CPU only, navigate to `environments/cpu`\n$ sudo docker compose up -d\n\n# Enter the container shell\n$ sudo docker compose exec core bash\n\n# Set up the virtual environment and install dependencies with Poetry\n$ poetry install\n```\n\nYou are now ready to start developing with Ascender.\n\n### Stop Development\n\n```bash\n# Stop the container\n$ cd environments/gpu  # Or `cd environments/cpu`\n$ sudo docker compose stop\n```\n\n## FAQ\n\n### Using Ascender Without Docker\n\nWhile we recommend using Docker as described, you may encounter issues installing Docker due to permissions or other constraints.\n\nIf you cannot use Docker, Ascender can be operated without it. Simply install Poetry on your computer and proceed as described in the \"Start Development\" section, omitting the Docker steps.\n\n```bash\n# Install Poetry\n$ pip3 install poetry\n\n# Clone the repository\n$ git clone git@github.com:\u003cYOUR_USER_NAME\u003e/\u003cYOUR_REPO_NAME\u003e.git\n$ cd \u003cYOUR_REPO_NAME\u003e\n\n# Set up the virtual environment and install dependencies with Poetry\n$ poetry install\n```\n\n\u003e \\[!Note\\]\n\u003e The CI jobs in Ascender's GitHub Actions workflows utilize a Dockerfile. Running without Docker may cause these jobs to fail, necessitating modifications to the Dockerfile or the deletion of the CI job (`.github/workflows/lint-and-test.yaml`).\n\n### Permission Errors When Running `poetry install`\n\nSometimes, running `poetry install` may result in a permission error:\n\n```bash\n$ poetry install\n...\n\nvirtualenv: error: argument dest: the destination . is not write-able at /home/challenger/ascender\n```\n\nIf this occurs, check your local PC's UID (user ID) and GID (group ID) with the following commands:\n\n```bash\n$ id -u $USER  # Check UID\n$ id -g $USER  # Check GID\n```\n\nIn Ascender, the default UID and GID are both '1000'. If your local PC's UID or GID differs from this, you'll need to adjust the 'UID' or 'GID' values in 'docker-compose.yaml' to match your local settings. Alternatively, if the 'HOST_UID' and 'HOST_GID' environment variables are set on your host PC, Ascender will use these values.\n\n### Compatibility Issues Between PyTorch and Poetry\n\n\u003e \\[!Note\\]\n\u003e Now poetry 1.2 is used in Ascender. So this issue is expected to be solved.\n\nAs of now, there is a known compatibility issue between PyTorch and Poetry, which the Poetry community is actively addressing. This issue is anticipated to be resolved in Poetry version 1.2.0. You can track progress and explore pre-releases of this version [here](https://github.com/python-poetry/poetry/releases/tag/1.2.0b3).\n\nWe plan to integrate Poetry 1.2.0 into Ascender as soon as it becomes available. In the meantime, you may need to use workarounds detailed in [this issue](https://github.com/python-poetry/poetry/issues/4231).\n\n**Related GitHub Issues**\n\n- [https://github.com/python-poetry/poetry/issues/2339](https://github.com/python-poetry/poetry/issues/2339)\n- [https://github.com/python-poetry/poetry/issues/2543](https://github.com/python-poetry/poetry/issues/2543)\n- [https://github.com/python-poetry/poetry/issues/2613](https://github.com/python-poetry/poetry/issues/2613)\n- [https://github.com/python-poetry/poetry/issues/3855](https://github.com/python-poetry/poetry/issues/3855)\n- [https://github.com/python-poetry/poetry/issues/4231](https://github.com/python-poetry/poetry/issues/4231)\n- [https://github.com/python-poetry/poetry/issues/4704](https://github.com/python-poetry/poetry/issues/4704)\n\n### Changing Python Versions for CI Jobs\n\nBy default, Ascender's CI jobs run using Python 3.8 and 3.9. If you wish to target a different Python version, modify [the matrix in `.github/workflows/lint-and-test.yaml`](https://github.com/cvpaperchallenge/Ascender/blob/master/.github/workflows/lint-and-test.yaml#L18).\n\n### Incorrect Reflection of Dockerfile Changes in Image Builds\n\nIf you find that changes to the Dockerfile are not reflected when building the image, try the following commands:\n\n```bash\n$ sudo docker compose build --no-cache\n$ sudo docker compose up --force-recreate -d\n```\n\nWhen changes to the Dockerfile are not reflected correctly, the potential reasons could be:\n\nDocker uses a cache to build the image.\nDocker does not recreate a container.\nThe `sudo docker compose build --no-cache` command builds the Docker image without using the cache, addressing the first issue. The `sudo docker compose up --force-recreate -d` command recreates and starts the containers, addressing the second issue.\n\n### Activating/Deactivating Caching in CI Jobs\n\nCaching was introduced in CI jobs (`lint-and-tests.yaml`) starting from `v0.1.2` to reduce delays caused by Docker image builds and Poetry installations. However, if you prefer not to use this feature, set the `USE_CACHE` variable in `lint-and-tests.yaml` to `false`.\n\n### Excessive Strictness of Ruff's Code Style Constraints\n\nIf you find the style checks enforced by Ruff too stringent, you can adjust the settings in `pyproject.toml` under `tool.ruff.[xxx]`.\n\n- `select`: Specify which Ruff style rules to apply.\n- `ignore`: Set rules to be ignored during style checking.\n- `fixable`: Allow automatic correction for certain fixable rules.\n- `unfixable`: Specify rules that should not be automatically corrected.\n\nFor details on each rule, please refer to [here](https://docs.astral.sh/ruff/rules/). For more information on how to configure the `pyproject.toml` file, see [here](https://docs.astral.sh/ruff/settings/).\n\n### Building multiple containers with Ascender’s template\n\nWhen using Ascender's templates for multiple projects, the following additional settings are necessary:\n\n- Specify port numbers: To avoid specifying the same port numbers as the existing containers, change the host PC's port in `environments/[cpu,gpu,ci]/docker-compose.yaml` from the default value.\n\n  ```yaml\n  ports:\n      - 8000:8000 # Example: Change to 8001:8000\n  ```\n\n- Change the project name: To prevent conflicting with the existing container names, change `PROJECT_NAME_ENV` in `environments/[cpu,gpu,ci]/.env`.\n\n  ```text\n  # If you need to change the default name of the project, edit the following.\n  PROJECT_NAME_ENV=ascender # Example: Change to a new project name\n  ```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcvpaperchallenge%2FAscender","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcvpaperchallenge%2FAscender","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcvpaperchallenge%2FAscender/lists"}