arches-containers 1.1.0rc2

A python developer tool for Arches Project that provides a way to create arches development environments. Supports Arches 6.1 to 8.0 (current development version).

Arches Containers

We are trialing the use of DeepWiki for developers to deepdive the code base (default branch only)

Overview

Arches Containers is a developer CLI tool to create and manage containerized Arches development environments. See Arches project for information related to the framework.

It is not an official Arches Project tool, but a community project to help developers get started with Arches development.

It provides commands to create and manage arches-container projects, which contain the necessary configuration files to run Arches in a containerized environment for development, complete with required minimum dependencies and services.

⚠️ It is not yet configured to build an image to be deployed to a hosted environment. The ability to create a basic deployable image is in the Roadmap.

These arches-container projects can be shared with others or stored in a version control system. They can be exported to a repository folder and imported back into the workspace.

It can also be used to generate VSCode debug configurations to allow debugging code inside the containers.

Installation

Throughout the documentation, the concept of a workspace is mentioned. This is the root working directory where the Arches projects and core repos sit.

It is recommended that you use a virtual environment within the workspace. The following instructions assume you are in the workspace directory.

cd /path/to/workspace
python -m venv env
source env/bin/activate  # On Windows use `env\Scripts\activate`

See the Arches documentation for more information.

From PyPI

1. Install the package:

   pip install arches-containers
   

Usage

Use the arches-containers or shorthand act command to manage arches-container projects.

The following examples use the act command. Replace act with arches-containers if you prefer to use the full command.

⚠️ arches-containers will create a .arches-containers folder in the workspace directory to store project configurations. It will look for this up the file tree when running commands. Should there be another .arches-containers folder in the workspace directory, the CLI may not work as expected.

cd /path/to/workspace
act [OPTIONS] COMMAND [ARGS]...

Note: The command is aliased as act for convenience (arches-container tool).

Quick start

1. Create a new project:

   This creates the arches-container project configuration and sets it as the active project.

   Run without arguments to use the interactive prompts:

   act create
   

   Or pass arguments directly:

   act create -p my_project -v 8.1 --activate
   

2. Start the project:

   This sets up the Arches repo, runs initialisation if needed, then starts the containers and the Arches development server.

   act up
   

3. Open a browser and navigate to http://localhost:8002 once setup and webpack builds are complete.

Create a Project

Steps to create a new container project.

Run without arguments to use the interactive prompts — you will be asked to type a project name and then select an Arches version from the available templates:

cd /path/to/workspace
act create

Or pass all arguments directly:

cd /path/to/workspace
act create -p <project_name> -v <version> [-r <repo_name>] [-o <organization>] [--activate]

• -p, --project_name: The name of the project. This value will be slugified to lowercase with underscore separators. If omitted, you will be prompted to enter one.
• -v, --version, --ver: The Arches version the project will be using (major.minor format). If omitted, you will be presented with a list of available versions sourced from the bundled templates, sorted newest-first. Unsupported versions are labelled.
• -r, --repo_name: The name of the local repository folder to create for the project. v7.6 and higher only.
• -o, --organization: The GitHub organization of the Arches repo (default: archesproject).
• --activate: Activate the project after creation. If it is the first project then it will be activated by default.

Managing Projects

The following commands are available for managing projects:

Start a Project

cd /path/to/workspace
act up [-p <project_name>] [-b] [-vb] [--app | --dep]

• -p, --project_name: The name of the project. If excluded, the active project will be used.
• -b, --build: Rebuild containers when composing up.
• -vb, --verbose: Print verbose output during the compose processes.
• --app: Only operate on application containers (docker-compose.yml). Mutually exclusive with --dep.
• --dep: Only operate on dependency containers (docker-compose-dependencies.yml). Mutually exclusive with --app.

Stop a Project

cd /path/to/workspace
act down [-p <project_name>] [-vb] [--app | --dep]

• -p, --project_name: The name of the project. If excluded, the active project will be used.
• -vb, --verbose: Print verbose output during the compose processes.
• --app: Only operate on application containers (docker-compose.yml). Mutually exclusive with --dep.
• --dep: Only operate on dependency containers (docker-compose-dependencies.yml). Mutually exclusive with --app.

Restart a Project

Restarts the project containers by stopping and then starting them. Useful for applying changes such as new dependencies or forcing a rebuild. Always operates on the active project.

ℹ️ The restart command will fail if the active project's containers are not currently running. Use act up to start the project first.

cd /path/to/workspace
act restart [-b] [-vb] [--app | --dep]

• -b, --build: Rebuild containers when composing up (after stopping them).
• -vb, --verbose: Print verbose output during the compose processes.
• --app: Only operate on application containers (docker-compose.yml). Mutually exclusive with --dep.
• --dep: Only operate on dependency containers (docker-compose-dependencies.yml). Mutually exclusive with --app.

Examples:

Restart and force rebuild:

act restart -b

Restart with verbose output:

act restart -b -vb

Restart only application containers:

act restart --app

Restart only dependency containers with rebuild:

act restart --dep -b

Activate a Project

Run without -p to choose from an interactive list of available projects (the currently active project is labelled):

cd /path/to/workspace
act activate

Or pass the project name directly:

cd /path/to/workspace
act activate -p <project_name> [-vb]

• -p, --project_name: The name of the project to activate. If omitted, an interactive selector is shown.
• -vb, --verbose: Print verbose output during the compose processes.

ℹ️ Activating a different project will fail if the current active project's containers are running. Use act down to stop them first.

List Projects

Steps to list all container projects.

cd /path/to/workspace
act list

Delete a Project

Run without -p to choose from an interactive list of available projects (the currently active project is labelled). You will be asked to confirm before the project is deleted:

cd /path/to/workspace
act delete

Or pass the project name directly:

cd /path/to/workspace
act delete [-p <project_name>]

• -p, --project_name: The name of the project to delete. If omitted, an interactive selector is shown.

Generate Debug Config

Steps to generate a VSCode launch.json configuration for the workspace.

cd /path/to/workspace
act generate-debug-config

Export a Project

The user can export an arches-container project to a repository folder. This is useful when the user wants to share the project with others or store it in a version control system. The export command will create a folder called .ac_<project_name> in the repository folder and copy the necessary files to it.

The docker compose files in the exported arches-container project will need to be run manually as the command only accesses those in the .arches-containers folder.

Run without -p to choose from an interactive list of available projects:

cd /path/to/workspace
act export

Or pass arguments directly:

cd /path/to/workspace
act export [-p <project_name>] [-r <repo_path>] [--keep-repo-hash] [--yes|--no]

• -p, --project_name: The name of the project to export. If omitted, an interactive selector is shown.
• -r, --repo_path: The path to the repository folder if different to the default.
• --keep-repo-hash: Keep the hash from an existing .ac_<project_name> config in the target repository.
• --yes: Answer yes to all export prompts (non-interactive mode).
• --no: Answer no to all export prompts (non-interactive mode).

If --keep-repo-hash is not passed and the target .ac_<project_name> already has a hash in config.json, the CLI prompts whether to keep that hash so teammates can import updates without creating new Docker objects.

Import a Project

The user can import an arches-container project from a repository folder. This is useful when the user wants to use a project that has been shared with them or stored in a version control system.

Run without -p to discover importable projects automatically. The CLI scans the workspace for .ac_*/config.json files at any depth and presents a list to choose from. Where the same project name exists in multiple locations, the relative path is shown to disambiguate:

cd /path/to/workspace
act import

Or pass arguments directly:

act import [-p <project_name>] [-r <repo_path>] [--new-hash | --hash <abc12>] [--yes|--no]

• -p, --project_name: The name of the project to import. If omitted, importable projects are discovered interactively.
• -r, --repo_path: The path to the repository folder if different to the default.
• --new-hash: Generate a new hash for the imported project.
• --hash: Set an explicit 5-character lowercase hexadecimal hash for the imported project.
• --yes: Answer yes to all import prompts (non-interactive mode).
• --no: Answer no to all import prompts (non-interactive mode).

If neither --new-hash nor --hash is passed, the CLI prompts whether to generate a new hash. This helps avoid accidental collisions with another running environment using the same Docker resource names.

example:

Given the following directory structure:

workspace
├── project1
│   ├── .ac_project1
│   └── ...
└── a_different_repo
    ├── .ac_project2
    └── ...

To import project1:

cd /path/to/workspace
act import -p project1

To import project2:

cd /path/to/workspace
act import -p project2 -r ./a_different_repo

Rehash a Project

Rehash updates the active project hash (or a named project hash) and rewrites hash references in project files.

act rehash [-p <project_name>] [--hash <abc12>]

• -p, --project_name: The project to rehash. Defaults to the active project.
• --hash: Set an explicit 5-character lowercase hexadecimal hash. If omitted, a new hash is generated.

rehash checks for running containers and aborts if any are running to avoid orphaning Docker resources.

Check Container Status

Steps to check container status of the active project.

cd /path/to/workspace
act status

Open a Shell in a Container

Opens an interactive bash shell inside a project container. Defaults to the main application container.

cd /path/to/workspace
act shell [-p <project_name>] [-c <container_name>] [--exec "<command>"]

• -p, --project_name: The name of the project. If excluded, the active project will be used.
• -c, --container: The name of the container to open a shell in. Defaults to the main application container.
• --exec: A command to run in the container non-interactively instead of opening a shell. Useful for scripting. Value should be between quotes.

Examples:

Open an interactive shell in the default container:

act shell

Open a shell in a specific container:

act shell -c my-project-db

Run a one-off command non-interactively (exit code is propagated):

act shell --exec "python manage.py show_graphs"

View Container Logs

Shows logs for a project container. Defaults to the main application container.

cd /path/to/workspace
act logs [-p <project_name>] [-c <container_name>] [-f]

• -p, --project_name: The name of the project. If excluded, the active project will be used.
• -c, --container: The name of the container to show logs for. Defaults to the main application container.
• -f, --follow: Follow the log output (like docker logs -f). Press Ctrl+C to stop.

Examples:

View logs of the default container:

act logs

Follow logs in real time:

act logs -f

View logs of a specific container:

act logs -c my-project-db

Quickly open the application in a browser

Steps to open the application in a browser.

cd /path/to/workspace
act view

Configuration of the Project

The project is stored in a directory called <workspace_path>/.arches-containers/<project_name> (the project path)and is compromised of a config file and a variety of files used with docker compose to stand up and environment.

The project configuration file config.json is used to store default values for the CLI commands when the project is activated.

example:

{
  "project_name": "arches_her_project",
  "project_name_url_safe": "archesherproject",
  "project_repo_directory": "arches-her-project",
    "arches_version": "8.1",
    "arches_repo_organization": "archesproject",
    "arches_repo_branch": "stable/8.1.0"
}

The project_repo_directory stores the name of the local repository folder for the project and supports hyphenated (kebab-case) directory names for Arches v7.6+.

When in the project directory, there are two files that you may want to configure:

• <project path>/docker/env_file.env: This file contains environment variables that are used by the docker-compose files. You can add or remove variables as needed.

• <project path>/docker/settings_local.py: This file is copied into the arches project when the container is started. If you need to set specific development environment settings, do it here. Note that if you change the settings_local.py file copied to the your arches project directory, it will be overwritten when the container is next stopped/started/restarted, so you should always change it in the <project path>/docker/settings_local.py file.

  ROADMAP - We'll look to provide a way to manage settings_local.py synchronisation in the future as part of the up and down commands.

Testing

The project uses pytest for testing. To run the tests, use the following command:

cd /path/to/arches-containers
pytest

Publishing

Publishing to PyPI and TestPyPI is handled by GitHub Actions triggered on a release (to PyPI) or a merge into the testpypi branch (to TestPyPI).

Version Numbering

Ensure the version number is updated in both pyproject.toml and the arches_containers/__init__.py file before triggering either action:

• For PyPI releases (triggered by GitHub release):

  • Final release: 1.2.0
  • Release candidate: 1.2.0rc1

• For TestPyPI releases (triggered by merge to testpypi branch):

  • Development release: 1.2.0.dev1
  • Alpha release: 1.2.0a1
  • Beta release: 1.2.0b1

Development Status Classifier

Also update the Development Status classifier in pyproject.toml to match your release type:

• For PyPI releases:

  "Development Status :: 5 - Production/Stable"  # For final releases
  "Development Status :: 4 - Beta"               # For release candidates
  

• For TestPyPI releases:

  "Development Status :: 3 - Alpha"              # For alpha/development releases
  "Development Status :: 4 - Beta"               # For beta releases
  

This ensures that both the version number and the development status accurately reflect the maturity of your release.

Contributing

Guidelines for contributing to the project are still being decided. Please check back later for more information.

The key principles are:

• It is designed to onboard new developers to the Arches project so the commands should be easy to understand and use.
• Keep the the functionality as simple as possible.
• Advanced functionality should not be a requirement for the majority of users.

While we work out the contribution guyideline, the following steps can be followed:

1. Fork the repository and create your branch from the deafult branch (dev/a.b.x).
2. Raise a ticket with details of the enhancement or bug being fixed.
3. Write or update tests as necessary. Please ensure that all tests pass before submitting a pull request.
4. Submit a pull request with a clear description of the changes.

License

This project is licensed under the GNU AFFERO GENERAL PUBLIC LICENSE Version 3.