---
name: assisted-service-dev-mode
description: Build and code-generate assisted-service using skipper with podman. Use when running make targets, building the service, regenerating code from swagger or CRDs, running linters, or any containerized development task. Also use when the user encounters build errors, needs to set up their development environment, or asks about how to run tests.
---

# Assisted Service Dev Mode

## Skipper Overview

This project uses [skipper](https://github.com/Stratoscale/skipper) to run make targets inside a container built from `Dockerfile.assisted-service-build`. The container runtime is **podman**.

## Prerequisites — Python venv for skipper

Skipper is a Python CLI tool. Always activate the project venv before using it:

```bash
source .venv/bin/activate
```

If `.venv` does not exist, create it using the **system python** (some IDEs bundle their own Python which can hijack venv symlinks):

```bash
env -i HOME=$HOME PATH=/usr/bin:/usr/sbin:/bin:/sbin /usr/bin/python3 -m venv .venv
source .venv/bin/activate
pip install 'setuptools<81' strato-skipper
```

Key details:
- Must use `env -i ... /usr/bin/python3 -m venv` to avoid IDE-bundled python interception
- `setuptools<81` is required because skipper depends on `pkg_resources` which was removed in setuptools 82+

## Running Make Targets

Always activate the venv first, then run make targets through skipper:

```bash
source .venv/bin/activate
skipper make <target>
```

Skipper builds the container image defined in `skipper.yaml` and runs the make target inside it. The inner Makefile is `hack/Makefile`.

### Environment

- Container runtime: **podman** (configured via `CONTAINER_HOST` in `skipper.yaml`)
- Environment variables passed through: listed in `skipper.env`
- Go module cache mounted at `/go/pkg/mod` (from `~/.cache/go-build`)

## Common Targets

### Code Generation

After modifying `swagger.yaml`:
```bash
skipper make generate-from-swagger
```

After modifying CRD types in `api/`:
```bash
skipper make generate
```

The `generate` target runs (in order):
1. `generate-from-swagger` — regenerates `restapi/`, `client/`, `models/`
2. `generate-go` — runs `go mod tidy && go mod vendor` for all modules
3. `generate-events` — regenerates event types
4. `generate-mocks` — regenerates mock files
5. `generate-configuration` — regenerates config
6. `generate-bundle` — regenerates OLM bundle and CRD manifests

CRD manifests are generated by `controller-gen` inside `generate_manifests` / `generate_bundle` in `hack/generate.sh`. This produces:
- `config/crd/bases/*.yaml`
- `config/crd/resources.yaml`
- `deploy/olm-catalog/manifests/*.yaml`

### Building

```bash
skipper make build-minimal    # Build binary only
skipper make build-image      # Build container image
skipper make all              # Lint + test + build
```

### Linting

```bash
skipper make lint       # Run all linters
skipper make format     # Auto-format code
```

### Testing

```bash
skipper make unit-test         # Full unit tests (needs DB)
skipper make subsystem-test    # Subsystem tests (needs k8s)
```

## Passing Extra Environment Variables

Variables listed in `skipper.env` are automatically forwarded into the container. To pass additional variables for a single invocation, use the `-e` flag:

```bash
skipper -e FOO=bar make target
skipper -e SERVICE_IMAGE=quay.io/user/img:tag make build-image
```

Multiple variables can be passed by repeating `-e`:

```bash
skipper -e VAR1=val1 -e VAR2=val2 make target
```

## Troubleshooting

### `skipper: command not found`

The venv is not activated. Run:
```bash
source .venv/bin/activate
```
If `.venv` doesn't exist, follow the **Prerequisites** section above to create it.

### `pkg_resources` import errors / `ModuleNotFoundError: No module named 'pkg_resources'`

The installed `setuptools` version is too new (82+). Reinstall with the pinned version:
```bash
source .venv/bin/activate
pip install 'setuptools<81'
```

### Container image build failures

Skipper builds its container from `Dockerfile.assisted-service-build` (referenced in `skipper.yaml`). If the build fails:
- Check the Dockerfile for syntax or dependency issues
- Ensure podman is running: `systemctl --user status podman.socket`
- Try a clean rebuild: `podman rmi` the cached build image, then re-run

### Permission errors with podman

- Verify `CONTAINER_HOST` is set correctly in `skipper.yaml`
- Check that the podman socket is active: `systemctl --user start podman.socket`
- Ensure `$XDG_RUNTIME_DIR/podman/podman.sock` exists and is accessible

### `venv` creates broken symlinks

Some IDEs bundle their own Python, causing `python3 -m venv` to create symlinks pointing at the IDE's Python rather than the system one. Always create the venv with the explicit system path:
```bash
env -i HOME=$HOME PATH=/usr/bin:/usr/sbin:/bin:/sbin /usr/bin/python3 -m venv .venv
```

## Important Notes

- The outer `Makefile` delegates to `hack/Makefile` via skipper
- `generate_manifests()` in `hack/generate.sh` requires `ENABLE_KUBE_API=true` (set automatically by `generate_bundle`)
- Vendor directories (`vendor/`, `api/vendor/`, `client/vendor/`) are managed by `generate-go` target — don't manually edit vendored files
- After changing CRD type definitions in `api/hiveextension/v1beta1/`, run `skipper make generate` to regenerate CRD YAMLs and vendored copies