# Adding a new service

## Python setup

Install the [uv](https://docs.astral.sh/uv/) package manager

## CLI (Command-Line Interface)

We have our own cli called `agebd`.

To use the cli, first clone this repo. Then:

```
cd cli
uv sync
source .venv/bin/activate
agebd --help
```

### Adding a new service

```
agebd service add --help
```

## Environments

The services are deployed to 2 environments:

|  Environment | Network | Host | Deploy path on host |
|---|---|---|---|
|`prod` | `machine`| `sls-vserv-bd-hla01`     | `/sls/bd/hla/prod/` |
| `dev` | `office` | `sls-vserv-bd-hla01-dev` | `/sls/bd/hla/dev/` |


### Process Variables (PVs)

We distinguish between 

- `prod` vs `dev` PVs 
- **service specific** PVs from a dedicated IOC vs **external** PVs from other IOCs

#### PVs - Service Specific 

You create them, see (# TODO: docs...)

`prod` and `dev` PVs automatically get created.

In your code, you only use the `prod` name of a PV. The framework will automatically use the 
`dev` name/PV when a service runs in the `dev` environment.

#### PVs - External

The framework will use the same PV in `prod` and `dev`, i.e. there is no `dev` PV.
However, in `dev` you can only read from the PV, whereas in `prod` you can also write to it.

#### PVs - Examples

|  Environment | Service Specific | External |
|---|---|---|
|`prod` | `PV("AGEBD-MYSERVICE:MYPVNAME")` read&write      | `PV("AGEOP-SOME-SERVICE:SOME-PVNAME")` read&write  |
| `dev` | `PV("AGEBD-MYSERVICE-DEV:MYPVNAME")`  read&write | `PV("AGEOP-SOME-SERVICE:SOME-PVNAME")` readonly    |

### Python 

For python services there are 3 environments. The python environment is set through the env variable `AGEBD_ENV`.

|  Environment | PVs |
|---|---|
| `AGEBD_ENV=prod`  | uses `prod` PVs   |
| `AGEBD_ENV=dev`   | uses `dev` PVs    |
| `AGEBD_ENV=local` | uses fake/mock python objects as PVs, no access to real PVs |