77 lines
4.8 KiB
Markdown
77 lines
4.8 KiB
Markdown
# AS400API (.NET 9 + ODBC + Dev Container)
|
||
|
||
## Quick start
|
||
1) Put IBM i Access ODBC RPM into `drivers/` and rename it to end with `.rpm.disabled` (e.g. `ibm-iaccess-1.1.x.x86_64.rpm.disabled`). The build converts it back to `.rpm` but the suffix prevents Apple Silicon devcontainer scaffolding from trying to install the amd64-only driver.
|
||
2) Build & run:
|
||
```bash
|
||
docker compose up --build
|
||
```
|
||
3) Open http://localhost:8080/swagger
|
||
|
||
### VS Code / F5
|
||
- Launch profile `AS400API` runs `dotnet run` with hot reload-ready JWT setup.
|
||
|
||
## Environment
|
||
- Uses `System.Data.Odbc`
|
||
- Driver name: `IBM i Access ODBC Driver` (from ACS). Adjust `AS400_DRIVER_NAME` if your driver name differs.
|
||
- Credentials are passed via env vars in `docker-compose.yml`.
|
||
|
||
## Authentication & Authorization
|
||
- `POST /api/auth/login` (anonymous) → request body `{ "username": "admin", "password": "Pass@123" }`.
|
||
- Demo identities live in-memory so you can plug in real IdP/Keycloak later.
|
||
- Default accounts:
|
||
- `admin` / `Pass@123` → roles: `Admin`, `Operator`
|
||
- `operator` / `Pass@123` → role: `Operator`
|
||
- Copy the `accessToken` from the response and send it as: `Authorization: Bearer <token>`.
|
||
- Override JWT issuer/audience/secret via `appsettings.json` or environment variables (`Jwt__Key`, etc.).
|
||
|
||
## Endpoints (role scoped)
|
||
- `GET /api/v1/health` → anonymous AS/400 ping via `SYSIBM.SYSDUMMY1`
|
||
- `GET /api/v1/users/me` → requires any authenticated user; echoes claims
|
||
- `GET /api/v1/as400/databases` → requires `Operator` or `Admin`
|
||
- `GET /api/v1/as400/query?sql=...` → requires `Admin`
|
||
- `GET /api/v1/as400/tables?libraryName=LIB` → requires `Operator` or `Admin`
|
||
- `GET /api/v1/as400/table-structure?libraryName=LIB&tableName=TBL` → requires `Operator` or `Admin`
|
||
|
||
## Logging
|
||
- Serilog writes rolling files by default to `Logs/as400-api-.log` (configurable in `appsettings.json:Serilog:WriteTo:0:Args:path`).
|
||
- Override at runtime with environment variables, e.g. `Serilog__WriteTo__0__Args__path=/var/log/as400/api-.log`.
|
||
- Request logging middleware is enabled; application-specific events (query counts, failures, etc.) are captured with structured properties to aid analysis.
|
||
|
||
## Jenkins CI notes
|
||
- The repo includes a declarative Jenkinsfile that builds on the `mcr.microsoft.com/dotnet/sdk:9.0` container image and expects Jenkins parameters for `GIT_REPO_URL`, `GIT_CREDENTIALS_ID`, `SONARQUBE_SERVER`, and `SONAR_TOKEN_ID`. Create the credentials in **Manage Jenkins › Credentials** before running the job.
|
||
- Update the Sonar project key or organization by editing `SONAR_PROJECT_KEY` / `SONAR_ORG` in the Jenkins parameter defaults or overriding them per-run; the pipeline passes these values to `dotnet-sonarscanner`.
|
||
- The pipeline publishes unit-test results, OpenCover XML, and HTML coverage reports; open the “Code Coverage” HTML report in the Jenkins build sidebar or download the archived artifacts `artifacts/AS400API-<build>-<commit>/reports/coverage-html/index.html`.
|
||
- SCA results (`security-reports/nuget-vulnerabilities.txt` and optional Dependency-Check HTML) and application logs from `Logs/` are archived automatically so you can review findings without re-running the build.
|
||
|
||
## SonarQube analysis
|
||
- Install or provision a SonarQube/SonarCloud server and generate a project token.
|
||
- Set environment variables (`SONAR_HOST_URL`, `SONAR_TOKEN`, optionally `SONAR_PROJECT_KEY`, `SONAR_PROJECT_NAME`; defaults are `as400api` / `AS400API`, plus `SONAR_ORGANIZATION` for SonarCloud).
|
||
- Run `scripts/run-sonar.sh`; the script builds the solution, runs tests with Coverlet coverage (when `*Tests.csproj` projects exist), and publishes results.
|
||
- Provide branch and pull request details with `SONAR_BRANCH_NAME`, `SONAR_PULL_REQUEST_KEY`, `SONAR_PULL_REQUEST_BRANCH`, and `SONAR_PULL_REQUEST_BASE` when needed.
|
||
|
||
## Notes
|
||
- On first build, if no RPM exists in `drivers/`, the image will build but ODBC won't work until you add the RPM and rebuild.
|
||
|
||
## Kubernetes deployment
|
||
Use the manifests in `k8s/` when running the API on Kubernetes.
|
||
|
||
1. Create a secret with the AS/400 password (and optional JWT key) so it stays separate from the rest of the configuration:
|
||
```bash
|
||
cp k8s/secret-example.yaml k8s/secret.yaml
|
||
# edit k8s/secret.yaml and set real values
|
||
kubectl apply -f k8s/secret.yaml
|
||
```
|
||
Alternatively create the secret imperatively: `kubectl create secret generic as400api-secrets --from-literal=AS400_PASSWORD=... --from-literal=JWT__KEY=...`.
|
||
2. Apply the non-sensitive settings:
|
||
```bash
|
||
kubectl apply -f k8s/configmap.yaml
|
||
```
|
||
3. Deploy the workload and service:
|
||
```bash
|
||
kubectl apply -f k8s/deployment.yaml
|
||
kubectl apply -f k8s/service.yaml
|
||
```
|
||
|
||
The deployment imports the configuration via `envFrom` so the password is sourced from the secret while everything else comes from the config map. Update image names, probes, and resource requests to fit your environment.
|