# IOC

The following instructions explain the basics of starting and managing IOCs on the IOC host.
They describe the manual steps. In practice the CI/CD runner does this for you, see
[Automation](#automation) below. 

- TODO: some iocs not associated to a service, where to put? 
- TODO: need to dev/prod template them too

## Host 

`sls-vserv-bd-01(-dev)`

## Shell

Start up an IOC shell:

```shell
iocsh AGEBD-CPCL-MASTER_main.subs
```

or:

```shell
ioc shell AGEBD-CPCL-MASTER-DEV
```

then you can run commands to interact with EPICS.

List available PVs:

```shell
> dbl
```

Exit:

```shell
Ctrl + d
```


## Install

For existing IOCs, a login to the IOC and a restart via `ctrl+x` is sufficient.

On `sls-lc*`

```shell
ioc install -V --ioc AGEBD-CPCL-PLAYGROUND --clean
ioc shell AGEBD-CPCL-PLAYGROUND
ctrl+x
```

For the initial install, additionally, the shellbox on the ioc host must be restarted. 

```shell
sudo shellbox reload            # new ioc installed
```

Result: on ioc host, e.g. `sls-vserv-bd-01-dev`

```shell
vim /etc/shellbox/<port-number>
```

### Local Tests

```shell
iocsh AGEBD-CPCL-PLAYGROUND_main.subs
```

using template file:

```shell
iocsh PLAYGROUND.template DEVICE=TEST
```

## "Delete"

There is no way to really delete an IOC through the `ioc` cli.

What you can do: `ssh sls-lc*` and delete the entry from `/ioc/hosts/sls-vserv-bd-01(-dev)/shellbox.conf`

## Restart an IOC via shellbox

On BD host `sls-vserv-bd-01(-dev)`

```shell
sudo shellbox reload            # new ioc installed
sudo shellbox status            # status of all iocs on server
sudo shellbox stop 50045        # stop ioc
sudo shellbox start 50045       # start ioc
sudo shellbox log 50045 -f      # log file (tail)
exit                            # exit ssh
```


## Automation

Installing, starting and restarting IOCs is done by the gitea runner, not by hand:

- `.gitea/scripts/ioc-install.sh <service-name> <dev|prod>`
- `.gitea/scripts/ioc-start.sh <service-name> <dev|prod>` (shellbox, over `ssh`)
- `.gitea/scripts/ioc-restart.sh <service-name> <dev|prod>`

The scripts operate on the deployed IOC files in
`/sls/bd/hla/<env>/services/<service-name>/current/ioc`, so a service has to be deployed
before its IOC can be installed.

They run automatically when a new service is added (`.gitea/workflows/add-new-service.yml`),
and can be triggered manually for any service (or `all` services) through the `Ioc` workflow
(`.gitea/workflows/ioc.yml`) in the gitea Actions tab.