kenkeep Index
Bundle OKF 0.1 · 0 conceitos · factorial-io/scotty
Open source Repository Open in the app JSON README (API)
About
# kenkeep Index
> kenkeep navigation: the injected body above is the root index node, the top-level catalog of branches and root-level leaves. Do not expect the whole knowledge base here; descend on demand. Read the root index node, pick one or more branches whose intent and tags match your task (several branches can be relevant), and read those branch `index.md` nodes. Descend further only where the task needs it, opening only the leaves you have confirmed are relevant. Follow each leaf's `relates_to` and `depends_on` cross edges to reach related leaves in other branches. You decide how deep to go per branch.
> This index only orients you; leaves hold the durable guidance. Open at least one relevant leaf before acting.
## Subfolders
- Load [`apps/`](apps/index.md) for more information on app lifecycle, anatomy, blueprints, custom actions, and container status/log behavior; read when creating or managing apps, changing lifecycle state machines, or touching log streaming.
- Load [`ar
Details
- Kind
- OKF bundles
- Topic
- AI, RAG & memory
- Publisher
- factorial-io
- Origin
- okf_github
- Category
- dados
- Version
- 0.1
- Stars
- 14
- Forks
- 1
- Open pull requests
- 10
- Last push
- 2026-09-10T05:41:03Z
- Repository state
- ativo
- Language
- Rust
- License
- MIT
- Added
- 2026-09-09 05:03:59
- Updated
- 2026-09-09 05:03:59
- Origin id
factorial-io/scotty:.ai/kenkeep/nodes/index.md
README
<div align="center">
<img src="docs/content/assets/logo.svg" alt="Scotty" width="324" height="80">
</div>
## About
**scotty -- yet another micro platform as a service** is a Rust
server providing an API to create, start, stop or destroy a
Docker Compose-based application on your own hardware.
The repo contains two applications:
* `scotty` a Rust-based HTTP server providing an API to talk with the
service and to start, stop and run Docker Compose-based applications.
The service provides a user interface at e.g. `http://localhost:21342/`.
The API is documented at `http://localhost:21342/rapidoc`
* `scottyctl`, a CLI application to talk with the service and execute
commands from your shell
## Installation
Please have a look at the detailed installation instructions [here](docs/content/installation.md)
## CLI usage
You need to pass the address to the server to the CLI, either by providing
the `--server`-argument or by setting the `SCOTTY_SERVER` env-var.
```shell
scottyctl help
```
will show some help and a list of available commands. You can get help
with `scottyctl help <command>`. A complete list of commands is available [here](docs/content/cli.md)
Move files between your workstation and a service container with `app:cp`:
```shell
# Copy a file out of a container
scottyctl app:cp my-app:web:/var/log/app.log ./app.log
# Pipe a database dump into a container
mysqldump mydb | scottyctl app:cp - my-app:db:/tmp/dump.sql
```
### Shell autocompletion
Make sure to leverage `scottyctl completion $SHELL` to get autocompletion for
your shell, see [here](docs/content/installation.md).
## Configuring the CLI
### Option 1: OAuth Authentication (Recommended)
Use OAuth device flow for secure authentication:
```shell
# Authenticate with OAuth
scottyctl auth:login --server https://localhost:21342
# Use authenticated commands
scottyctl app:list
```
### Option 2: Bearer Token
Bearer tokens are configured on the server with logical identifiers that map to secure tokens. Use environment variables or command-line arguments:
```shell
# Via environment variables
export SCOTTY_SERVER=https://localhost:21342
export SCOTTY_ACCESS_TOKEN=your_secure_bearer_token
# Via command-line arguments
scottyctl --server https://localhost:21342 --access-token your_secure_bearer_token app:list
```
**Security Note**: Server administrators should **never store actual bearer tokens in configuration files**. Instead, use placeholder values in config files and set actual secure tokens via environment variables like `SCOTTY__API__BEARER_TOKENS__ADMIN=your_secure_token`. See the [configuration documentation](docs/content/configuration.md) for security best practices.
## Docker Deployment
### Quick Start with Docker
The Docker image includes only the binaries and non-sensitive configuration files (Casbin model, blueprints). Configuration with secrets must be provided at runtime.
**Option 1: Mount configuration directory (recommended)**
```bash
docker run -d \
-v /path/to/your/config:/app/config:ro \
-v /path/to/apps:/app/apps \
-v /var/run/docker.sock:/var/run/docker.sock \
-p 21342:21342 \
scotty:latest
```
**Option 2: Use environment variables**
```bash
docker run -d \
-e SCOTTY__API__AUTH_MODE=bearer \
-e SCOTTY__API__BEARER_TOKENS__ADMIN=your-secure-token \
-e SCOTTY__APPS__DOMAIN_SUFFIX=your-domain.site \
-p 21342:21342 \
scotty:latest
```
**Option 3: Docker Compose**
```yaml
services:
scotty:
image: scotty:latest
ports:
- "21342:21342"
volumes:
- ./config:/app/config:ro
- ./apps:/app/apps
- /var/run/docker.sock:/var/run/docker.sock
environment:
- SCOTTY__API__BEARER_TOKENS__ADMIN=${ADMIN_TOKEN}
restart: unless-stopped
```
**Important**: Never commit secrets to git. Use environment variables or mount configuration files at runtime. See [config/README.md](config/README.md) for detailed configuration documentation.
## Observability
Scotty includes a comprehensive observability stack with metrics, distributed tracing, and pre-built dashboards for monitoring application health and performance.
### Quick Start
Start the observability stack (Grafana, Jaeger, VictoriaMetrics, OpenTelemetry Collector):
```shell
cd observability
docker-compose up -d
```
Enable telemetry in Scotty:
```shell
SCOTTY__TELEMETRY=metrics,traces cargo run --bin scotty
```
Access the services:
- **Grafana Dashboard**: http://grafana.ddev.site (admin/admin)
- **Jaeger Tracing**: http://jaeger.ddev.site
- **VictoriaMetrics**: http://vm.ddev.site
### What's Monitored
Scotty exports 40+ metrics covering:
- Log streaming (active streams, throughput, errors)
- Shell sessions (active connections, timeouts)
- WebSocket connections and message rates
- Task execution and output streaming
- HTTP server performance by endpoint
- Memory usage (RSS and virtual)
- Application fleet metrics
- Tokio async runtime health
### Documentation
For complete setup instructions, metrics reference, and production deployment guide:
📖 **[Observability Documentation](docs/content/observability.md)**
📖 **[Observability Setup Guide](observability/README.md)**
## Developing/Contributing
We welcome contributions! Please fork the repository, create a
feature branch and submit a pull-request.
* Try to add tests for your bug fixes and features.
* Use conventional commits
### Requirements
To run the server locally you need to have Docker and Docker Compose
installed on your local machine. You also need a recent Rust toolchain.
To get things up and running please start Traefik with:
```shell
cd apps/traefik
docker-compose up -d
```
and then start the server with:
```shell
cargo run --bin scotty or your preferred way to run a rust binary
```
### AI knowledge base (kenkeep)
This repo ships a [kenkeep](https://github.com/e0ipso/kenkeep) knowledge base under `.ai/kenkeep/`. The Claude Code hook wiring in `.claude/settings.json` points at scripts under `.ai/kenkeep/hooks/`, which is machine-local and gitignored — after cloning, generate it once:
```shell
npx --yes kenkeep@latest init
```
Verify with `npx kenkeep doctor`. Without this step, Claude Code sessions in this repo will report hook failures ("cannot find module") on session start/end. See [.ai/kenkeep/README.md](.ai/kenkeep/README.md) for how the knowledge base works.
### Pre-push git hook via [cargo-husky](https://github.com/rhysd/cargo-husky)
This project uses a pre-push git-hook installed by cargo husky. It should be installed automatically.
### Create a new release
Releases are automated with [release-please](https://github.com/googleapis/release-please). There is **no manual tagging and no local release command** — you release by merging a pull request.
**Do not manually bump versions or edit `CHANGELOG.md`** — both are derived from the git history by release-please. All crates share a single workspace version, so every release bumps the whole workspace and produces one `vX.Y.Z` tag.
#### 1. Land changes with conventional commits
Use [conventional commits](https://www.conventionalcommits.org) on `main` (the squash-merge title of a PR counts). The commit type drives both the changelog section and the next version:
| Commit | Effect on the next version |
| ---------------------------------------------- | -------------------------- |
| `fix:` / `perf:` | patch (`0.2.9` → `0.2.10`) |
| `feat:` | minor (`0.2.9` → `0.3.0`) |
| `feat!:`, `fix!:`, or a `BREAKING CHANGE:` footer | major (`0.2.9` → `1.0.0`) |
| `docs:`, `refactor:`, `style:`, `test:`, `ci:`, `chore:` | no release on their own |
#### 2. Review the release PR
On every push to `main`, the `release-please` GitHub Actions workflow opens (and keeps updating) a **release PR** titled `chore: release <version>`. It contains the version bump (`[workspace.package].version` in `Cargo.toml`) and the regenerated `CHANGELOG.md`. Inspect this PR to preview exactly what will ship.
#### 3. Merge to ship
When you are ready, **merge the release PR**. release-please then tags `vX.Y.Z`, publishes the GitHub Release, and the same workflow automatically:
- builds and uploads the `scottyctl` binaries,
- bumps the Homebrew tap formula, and
- builds and pushes the versioned Docker image.
Nothing is released until that PR is merged, so it is safe to let commits accumulate and cut a release when it suits you.
Configuration lives in `release-please-config.json` (release type, changelog sections) and `.release-please-manifest.json` (current version).