Metadata-Version: 2.4
Name: python3-cyberfusion-carbon-txt-server
Version: 1.1
Summary: carbon-txt-server serves `carbon.txt` files.
Author-email: Cyberfusion <support@cyberfusion.io>
Project-URL: Source, https://github.com/CyberfusionIO/python3-cyberfusion-carbon-txt-server
Description-Content-Type: text/markdown
Requires-Dist: starlette==0.52.1
Requires-Dist: uvicorn==0.46.0
Requires-Dist: validators==0.35.0
Requires-Dist: tomli-w==1.0.0

# python3-cyberfusion-carbon-txt-server

carbon-txt-server serves `carbon.txt` files.

# Install

## PyPI

Run the following command to install the package from PyPI:

```
pip3 install python3-cyberfusion-carbon-txt-server
```

## Debian

Run the following commands to build a Debian package:

    mk-build-deps -i -t 'apt -o Debug::pkgProblemResolver=yes --no-install-recommends -y'
    dpkg-buildpackage -us -uc

# Configure

## App

The following environment variables may be specified:

```
; The app name is used in several places for this app to identify itself (string)
; Default: carbon-txt-server
APP_NAME=

; The server will bind to this host (string)
; Default: ::1
LISTEN_HOST=

; The server will listen to this port (integer)
; Default: 8080
LISTEN_PORT=

; IP addresses of proxies that are trusted with proxy headers (comma separated list of strings)
; Default: ::1
TRUSTED_PROXY_ADDRESSES=

; The path to your JSON database (string)
; Default: none
DATABASE_PATH=
```

Only `DATABASE_PATH` is required to be set. We recommend setting it to `/var/lib/carbon-txt-server.json`.

## JSON Database

Find an example JSON database in `carbon-txt-server.json`.

Properties:

* `domains`. List of domains that this carbon.txt is served for.
* `last_updated`. Date the carbon.txt was last updated.
* `org`. Organisation block.
  * `disclosures`. List of disclosures. Each disclosure has:
    * `doc_type`. One of `web-page`, `annual-report`, `sustainability-page`, `certificate`, `csrd-report`, `ai-model-card`, `other`.
    * `url`. URL of the disclosure document.
    * `valid_until` (optional). Date the disclosure is valid until.
    * `title` (optional). Title of the disclosure document.
* `upstream`. Upstream providers block.
  * `services`. List of upstream services. Each service has:
    * `domain`. Domain of the upstream service.
    * `service_type`. Service type as a string, or list of strings.

Find information about these properties on https://carbontxt.org/syntax.

# Usage

## Manually

    bin/carbon-txt-server

### systemd

    systemctl start carbon-txt-server.service

## SSL

Use a proxy that terminates SSL. E.g. [HAProxy](http://www.haproxy.org/).
