mirror of
https://github.com/lldap/lldap.git
synced 2026-03-31 15:07:48 +01:00
Add comprehensive GitHub Copilot instructions for LLDAP repository
Add copilot-setup-steps.yml for GitHub Copilot agent environment setup
This commit is contained in:
copilot-swe-agent[bot]
committed by
nitnelave
nitnelave
parent
5e83ed8eb0
commit
cd2694d7dc
@@ -0,0 +1,159 @@
|
|||||||
|
# LLDAP - Light LDAP implementation for authentication
|
||||||
|
|
||||||
|
LLDAP is a lightweight LDAP authentication server written in Rust with a WebAssembly frontend. It provides an opinionated, simplified LDAP interface for authentication and integrates with many popular services.
|
||||||
|
|
||||||
|
**ALWAYS reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.**
|
||||||
|
|
||||||
|
## Working Effectively
|
||||||
|
|
||||||
|
### Bootstrap and Build the Repository
|
||||||
|
- Install dependencies: `sudo apt-get update && sudo apt-get install -y curl gzip binaryen`
|
||||||
|
- Install Rust if not available: `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh` then `source ~/.cargo/env`
|
||||||
|
- Install wasm-pack for frontend: `cargo install wasm-pack` -- takes 90 seconds. NEVER CANCEL. Set timeout to 180+ seconds.
|
||||||
|
- Build entire workspace: `cargo build --workspace` -- takes 3-4 minutes. NEVER CANCEL. Set timeout to 300+ seconds.
|
||||||
|
- Build release server binary: `cargo build --release -p lldap` -- takes 5-6 minutes. NEVER CANCEL. Set timeout to 420+ seconds.
|
||||||
|
- Build frontend WASM: `./app/build.sh` -- takes 3-4 minutes including wasm-pack installation. NEVER CANCEL. Set timeout to 300+ seconds.
|
||||||
|
|
||||||
|
### Testing and Validation
|
||||||
|
- Run all tests: `cargo test --workspace` -- takes 2-3 minutes. NEVER CANCEL. Set timeout to 240+ seconds.
|
||||||
|
- Check formatting: `cargo fmt --all --check` -- takes <5 seconds.
|
||||||
|
- Run linting: `cargo clippy --tests --all -- -D warnings` -- takes 60-90 seconds. NEVER CANCEL. Set timeout to 120+ seconds.
|
||||||
|
- Export GraphQL schema: `./export_schema.sh` -- takes 70-80 seconds. NEVER CANCEL. Set timeout to 120+ seconds.
|
||||||
|
|
||||||
|
### Running the Application
|
||||||
|
- **ALWAYS run the build steps first before starting the server.**
|
||||||
|
- Start development server: `cargo run -- run --config-file <config_file>`
|
||||||
|
- **CRITICAL**: Server requires a valid configuration file. Use `lldap_config.docker_template.toml` as reference.
|
||||||
|
- **CRITICAL**: Avoid key conflicts by removing existing `server_key*` files when testing with `key_seed` in config.
|
||||||
|
- Server binds to:
|
||||||
|
- LDAP: port 3890 (configurable)
|
||||||
|
- Web interface: port 17170 (configurable)
|
||||||
|
- LDAPS: port 6360 (optional, disabled by default)
|
||||||
|
|
||||||
|
### Manual Validation Requirements
|
||||||
|
- **ALWAYS test both LDAP and web interfaces after making changes.**
|
||||||
|
- Test web interface: `curl -s http://localhost:17170/` should return HTML with "LLDAP Administration" title.
|
||||||
|
- Test GraphQL API: `curl -s -X POST -H "Content-Type: application/json" -d '{"query": "query { __schema { queryType { name } } }"}' http://localhost:17170/api/graphql`
|
||||||
|
- Run healthcheck: `cargo run -- healthcheck --config-file <config_file>` (requires running server)
|
||||||
|
- **ALWAYS ensure server starts without errors and serves the web interface before considering changes complete.**
|
||||||
|
|
||||||
|
## Validation Scenarios
|
||||||
|
|
||||||
|
After making code changes, ALWAYS:
|
||||||
|
1. **Build validation**: Run `cargo build --workspace` to ensure compilation succeeds.
|
||||||
|
2. **Test validation**: Run `cargo test --workspace` to ensure existing functionality works.
|
||||||
|
3. **Lint validation**: Run `cargo clippy --tests --all -- -D warnings` to catch potential issues.
|
||||||
|
4. **Format validation**: Run `cargo fmt --all --check` to ensure code style compliance.
|
||||||
|
5. **Frontend validation**: Run `./app/build.sh` to ensure WASM compilation succeeds.
|
||||||
|
6. **Runtime validation**: Start the server and verify web interface accessibility.
|
||||||
|
7. **Schema validation**: If GraphQL changes made, run `./export_schema.sh` to update schema.
|
||||||
|
|
||||||
|
### Test User Scenarios
|
||||||
|
- **Login flow**: Access web interface at `http://localhost:17170`, attempt login with admin/password (default).
|
||||||
|
- **LDAP binding**: Test LDAP connection on port 3890 with appropriate LDAP tools if available.
|
||||||
|
- **Configuration changes**: Test with different configuration files to validate config parsing.
|
||||||
|
|
||||||
|
## Project Structure and Key Components
|
||||||
|
|
||||||
|
### Backend (Rust)
|
||||||
|
- **Server**: `/server` - Main application binary
|
||||||
|
- **Crates**: `/crates/*` - Modularized components:
|
||||||
|
- `auth` - Authentication and OPAQUE protocol
|
||||||
|
- `domain*` - Domain models and handlers
|
||||||
|
- `ldap` - LDAP protocol implementation
|
||||||
|
- `graphql-server` - GraphQL API server
|
||||||
|
- `sql-backend-handler` - Database operations
|
||||||
|
- `validation` - Input validation utilities
|
||||||
|
|
||||||
|
### Frontend (Rust + WASM)
|
||||||
|
- **App**: `/app` - Yew-based WebAssembly frontend
|
||||||
|
- **Build**: `./app/build.sh` - Compiles Rust to WASM using wasm-pack
|
||||||
|
- **Assets**: `/app/static` - Static web assets
|
||||||
|
|
||||||
|
### Configuration and Deployment
|
||||||
|
- **Config template**: `lldap_config.docker_template.toml` - Reference configuration
|
||||||
|
- **Docker**: `Dockerfile` - Container build definition
|
||||||
|
- **Scripts**:
|
||||||
|
- `prepare-release.sh` - Cross-platform release builds
|
||||||
|
- `export_schema.sh` - GraphQL schema export
|
||||||
|
- `generate_secrets.sh` - Random secret generation
|
||||||
|
- `scripts/bootstrap.sh` - User/group management script
|
||||||
|
|
||||||
|
## Common Development Workflows
|
||||||
|
|
||||||
|
### Making Backend Changes
|
||||||
|
1. Edit Rust code in `/server` or `/crates`
|
||||||
|
2. Run `cargo build --workspace` to test compilation
|
||||||
|
3. Run `cargo test --workspace` to ensure tests pass
|
||||||
|
4. Run `cargo clippy --tests --all -- -D warnings` to check for warnings
|
||||||
|
5. If GraphQL schema affected, run `./export_schema.sh`
|
||||||
|
6. Test by running server and validating functionality
|
||||||
|
|
||||||
|
### Making Frontend Changes
|
||||||
|
1. Edit code in `/app/src`
|
||||||
|
2. Run `./app/build.sh` to rebuild WASM package
|
||||||
|
3. Start server and test web interface functionality
|
||||||
|
4. Verify no JavaScript errors in browser console
|
||||||
|
|
||||||
|
### Adding New Dependencies
|
||||||
|
- Backend: Add to appropriate `Cargo.toml` in `/server` or `/crates/*`
|
||||||
|
- Frontend: Add to `/app/Cargo.toml`
|
||||||
|
- **Always rebuild after dependency changes**
|
||||||
|
|
||||||
|
## CI/CD Integration
|
||||||
|
|
||||||
|
The repository uses GitHub Actions (`.github/workflows/rust.yml`):
|
||||||
|
- **Build job**: Validates workspace compilation
|
||||||
|
- **Test job**: Runs full test suite
|
||||||
|
- **Clippy job**: Linting with warnings as errors
|
||||||
|
- **Format job**: Code formatting validation
|
||||||
|
- **Coverage job**: Code coverage analysis
|
||||||
|
|
||||||
|
**ALWAYS ensure your changes pass all CI checks by running equivalent commands locally.**
|
||||||
|
|
||||||
|
## Timing Expectations and Timeouts
|
||||||
|
|
||||||
|
| Command | Expected Time | Timeout Setting |
|
||||||
|
|---------|---------------|-----------------|
|
||||||
|
| `cargo build --workspace` | 3-4 minutes | 300+ seconds |
|
||||||
|
| `cargo build --release -p lldap` | 5-6 minutes | 420+ seconds |
|
||||||
|
| `cargo test --workspace` | 2-3 minutes | 240+ seconds |
|
||||||
|
| `./app/build.sh` | 3-4 minutes | 300+ seconds |
|
||||||
|
| `cargo clippy --tests --all -- -D warnings` | 60-90 seconds | 120+ seconds |
|
||||||
|
| `./export_schema.sh` | 70-80 seconds | 120+ seconds |
|
||||||
|
| `cargo install wasm-pack` | 90 seconds | 180+ seconds |
|
||||||
|
|
||||||
|
**NEVER CANCEL** any of these commands. Builds may take longer on slower systems.
|
||||||
|
|
||||||
|
## Troubleshooting Common Issues
|
||||||
|
|
||||||
|
### Build Issues
|
||||||
|
- **Missing wasm-pack**: Run `cargo install wasm-pack`
|
||||||
|
- **Missing binaryen**: Run `sudo apt-get install -y binaryen` or disable wasm-opt
|
||||||
|
- **Clippy warnings**: Fix all warnings as they are treated as errors in CI
|
||||||
|
- **GraphQL schema mismatch**: Run `./export_schema.sh` to update schema
|
||||||
|
|
||||||
|
### Runtime Issues
|
||||||
|
- **Key conflicts**: Remove `server_key*` files when using `key_seed` in config
|
||||||
|
- **Port conflicts**: Check if ports 3890/17170 are available
|
||||||
|
- **Database issues**: Ensure database URL in config is valid and accessible
|
||||||
|
- **Asset missing**: Ensure frontend is built with `./app/build.sh`
|
||||||
|
|
||||||
|
### Development Environment
|
||||||
|
- **Rust version**: Use stable Rust toolchain (2024 edition)
|
||||||
|
- **System dependencies**: curl, gzip, build tools
|
||||||
|
- **Database**: SQLite (default), MySQL, or PostgreSQL supported
|
||||||
|
|
||||||
|
## Configuration Reference
|
||||||
|
|
||||||
|
Essential configuration parameters:
|
||||||
|
- `ldap_base_dn`: LDAP base DN (e.g., "dc=example,dc=com")
|
||||||
|
- `ldap_user_dn`: Admin user DN
|
||||||
|
- `ldap_user_pass`: Admin password
|
||||||
|
- `jwt_secret`: Secret for JWT tokens (generate with `./generate_secrets.sh`)
|
||||||
|
- `key_seed`: Encryption key seed
|
||||||
|
- `database_url`: Database connection string
|
||||||
|
- `http_port`: Web interface port (default: 17170)
|
||||||
|
- `ldap_port`: LDAP server port (default: 3890)
|
||||||
|
|
||||||
|
**Always use the provided config template as starting point for new configurations.**
|
||||||
@@ -0,0 +1,26 @@
|
|||||||
|
name: Copilot Setup Steps for LLDAP Development
|
||||||
|
|
||||||
|
steps:
|
||||||
|
- name: Update package list
|
||||||
|
run: sudo apt-get update
|
||||||
|
|
||||||
|
- name: Install system dependencies
|
||||||
|
run: sudo apt-get install -y curl gzip binaryen build-essential
|
||||||
|
|
||||||
|
- name: Install Rust toolchain
|
||||||
|
run: |
|
||||||
|
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
|
||||||
|
source ~/.cargo/env
|
||||||
|
echo 'source ~/.cargo/env' >> ~/.bashrc
|
||||||
|
|
||||||
|
- name: Install wasm-pack for frontend builds
|
||||||
|
run: |
|
||||||
|
source ~/.cargo/env
|
||||||
|
cargo install wasm-pack
|
||||||
|
|
||||||
|
- name: Verify installations
|
||||||
|
run: |
|
||||||
|
source ~/.cargo/env
|
||||||
|
rustc --version
|
||||||
|
cargo --version
|
||||||
|
wasm-pack --version
|
||||||
Generated
+3
-3
@@ -2506,7 +2506,7 @@ checksum = "78b3ae25bc7c8c38cec158d1f2757ee79e9b3740fbc7ccf0e59e4b08d793fa89"
|
|||||||
|
|
||||||
[[package]]
|
[[package]]
|
||||||
name = "lldap"
|
name = "lldap"
|
||||||
version = "0.6.2-alpha"
|
version = "0.6.2"
|
||||||
dependencies = [
|
dependencies = [
|
||||||
"actix",
|
"actix",
|
||||||
"actix-files",
|
"actix-files",
|
||||||
@@ -2532,7 +2532,7 @@ dependencies = [
|
|||||||
"futures-util",
|
"futures-util",
|
||||||
"graphql_client 0.11.0",
|
"graphql_client 0.11.0",
|
||||||
"hmac 0.12.1",
|
"hmac 0.12.1",
|
||||||
"http 1.1.0",
|
"http 0.2.12",
|
||||||
"juniper",
|
"juniper",
|
||||||
"jwt 0.16.0",
|
"jwt 0.16.0",
|
||||||
"ldap3",
|
"ldap3",
|
||||||
@@ -2599,7 +2599,7 @@ dependencies = [
|
|||||||
|
|
||||||
[[package]]
|
[[package]]
|
||||||
name = "lldap_app"
|
name = "lldap_app"
|
||||||
version = "0.6.2-alpha"
|
version = "0.6.2"
|
||||||
dependencies = [
|
dependencies = [
|
||||||
"anyhow",
|
"anyhow",
|
||||||
"base64 0.13.1",
|
"base64 0.13.1",
|
||||||
|
|||||||
Reference in New Issue
Block a user