design-system-chart-exporter

August 21, 2026 · View on GitHub

A FastAPI service for generating and exporting, ONS Design System chart images

Getting Started
- Pre-requisites
- Installation
Development
- Run Tests with Coverage
- Linting and Formatting
Contributing
License

Getting Started

To get a local copy up and running, follow these simple steps.

Pre-requisites

Ensure you have the following installed:

Python: Version specified in .python-version. We recommend using uv to install and pin the project Python version.
uv: This is used to manage package dependencies and virtual environments.
Docker
Operating System: Ubuntu/macOS

Installation

Clone the repository and install the required dependencies.

git clone https://github.com/ONSdigital/design-system-chart-exporter.git

Install dependencies

uv is used to manage dependencies in this project. For more information, read the uv documentation. To install the Python version pinned for this project, run:
```
uv python install
```
To install all dependencies, including development dependencies, run:
```
make install-dev
```
Install the Git hooks used for local validation:
```
make install-pre-commit
```
To install only production dependencies, run:
```
make install
```
To build the Docker image for the application, run:
```
make compose-build
```
Run the application

Locally via uv:
```
make run
```
Using Docker Compose:
```
make start
```

By default, the application will be available at http://localhost:30300. This can be customised by setting the WEB_PORT environment variable.

Development

Get started with development by running the following commands. Before proceeding, make sure you have the development dependencies installed using the make install-dev command.

A Makefile is provided to simplify common development tasks. To view all available commands, run:

make

Run Tests with Coverage

The unit tests are written using the pytest framework. To run the tests and check coverage, run:

make test

OpenAPI specification

The OpenAPI specification for the service is available at http://localhost:30300/openapi.json when the service is running locally.

The repository also contains a YAML version of the OpenAPI specification at ./openapi.yaml. This can be used to generate client code.

The file can be updated by running the following command:

make openapi

Linting and Formatting

Various tools are used to lint and format the code in this project.

Python

The project uses Ruff for linting and formatting, mypy for type checking, and pylint for additional linting of the Python code.

The tools are configured using the pyproject.toml file and .pylintrc.

To lint the Python code, run:

make lint

To auto-format the Python code, and correct fixable linting issues, run:

make format

To run the configured pre-commit hooks across the repository, run:

make pre-commit

MegaLinter (Lint/Format non-python files)

MegaLinter is utilised to lint the non-python files in the project. It offers a single interface to execute a suite of linters for multiple languages and formats, ensuring adherence to best practices and maintaining consistency across the repository without the need to install each linter individually.

MegaLinter examines various file types and tools, including GitHub Actions, Shell scripts, Dockerfile, etc. It is configured using the .mega-linter.yml file.

To run MegaLinter, ensure you have Docker installed on your system.

Note

If you use Colima for Docker on macOS, run colima start --edit and set mountType: virtiofs in the profile YAML so that bind mounts work correctly with make megalint.
The initial run may take some time while the Docker image is downloaded. Subsequent runs will be considerably faster due to Docker caching. 🚀

To start the linter and automatically rectify fixable issues, run:

make megalint

To run only a specific linter, pass LINTER variable:

make megalint LINTER=YAML_YAMLLINT

This maps to MegaLinter's ENABLE_LINTERS environment variable. See the supported linters list for valid names.

Logging

By default, the logging configuration is set to log messages at the INFO level and above.

Logging can be configured using the following environment variables:

Environment Variable	Description	Default Value
`LOG_LEVEL`	The logging level: `DEBUG`, `INFO`, `WARNING`, `ERROR`, or `CRITICAL`.	`INFO`
`LOG_AS_JSON`	Whether to log messages as JSON. One of `true` or `false`.	`true`

Contributing

See CONTRIBUTING.md for details.

License

Unless stated otherwise, the codebase is released under the MIT License. This covers both the codebase and any sample code in the documentation.

The documentation in this repo are released under the Open Government Licence v3.0.