- 1. Introduction
- 2. Recipe Categories
- 2.1. 📚 Help & Documentation Recipes
- 2.2. 🏗️ Build Recipes
- 2.2.1.
build - 2.2.2.
build-all - 2.2.3.
build-release - 2.2.4.
build-debug - 2.2.5.
build-core - 2.2.6.
build-core-debug - 2.2.7.
build-core-release - 2.2.8.
build-ai-jail - 2.2.9.
build-backend - 2.2.10.
build-office-addin - 2.2.11.
build-cli - 2.2.12.
build-shared - 2.2.13.
build-monitoring - 2.2.14.
build-website - 2.2.15.
build-cross-all - 2.2.16.
build-cross-linux - 2.2.17.
build-cross-macos - 2.2.18.
build-cross-windows - 2.2.19.
build-pgo
- 2.2.1.
- 2.3. 🐳 Docker Recipes
- 2.3.1.
docker-build - 2.3.2.
docker-build-no-cache - 2.3.3.
docker-build-core - 2.3.4.
docker-build-backend - 2.3.5.
docker-build-ai-jail - 2.3.6.
docker-build-nginx - 2.3.7.
docker-dev - 2.3.8.
docker-prod - 2.3.9.
docker-up - 2.3.10.
docker-down - 2.3.11.
docker-down-prod - 2.3.12.
docker-restart - 2.3.13.
docker-test - 2.3.14.
docker-test-core - 2.3.15.
docker-test-backend - 2.3.16.
docker-test-integration - 2.3.17.
docker-logs - 2.3.18.
docker-logs-core - 2.3.19.
docker-logs-backend - 2.3.20.
docker-logs-ai-jail - 2.3.21.
docker-logs-follow - 2.3.22.
docker-ps - 2.3.23.
docker-ps-all - 2.3.24.
docker-exec SERVICE CMD - 2.3.25.
docker-shell-core - 2.3.26.
docker-shell-backend - 2.3.27.
docker-shell-postgres - 2.3.28.
docker-shell-redis - 2.3.29.
docker-db-migrate - 2.3.30.
docker-db-rollback - 2.3.31.
docker-db-reset - 2.3.32.
docker-db-seed - 2.3.33.
docker-db-backup - 2.3.34.
docker-db-restore BACKUP_FILE - 2.3.35.
docker-reset - 2.3.36.
docker-clean - 2.3.37.
docker-clean-volumes - 2.3.38.
docker-clean-all - 2.3.39.
docker-stats - 2.3.40.
docker-stats-live - 2.3.41.
docker-prometheus - 2.3.42.
docker-grafana - 2.3.43.
docker-adminer - 2.3.44.
docker-version - 2.3.45.
docker-config - 2.3.46.
docker-images - 2.3.47.
docker-volumes - 2.3.48.
docker-networks - 2.3.49.
docker-inspect CONTAINER - 2.3.50.
docker-disk-usage
- 2.3.1.
- 2.4. 🧪 Test Recipes
- 2.4.1.
test - 2.4.2.
test-all - 2.4.3.
test-unit - 2.4.4.
test-rust - 2.4.5.
test-rust-release - 2.4.6.
test-rust-verbose - 2.4.7.
test-rust-single - 2.4.8.
test-rust-specific TEST - 2.4.9.
test-elixir - 2.4.10.
test-elixir-verbose - 2.4.11.
test-elixir-specific TEST - 2.4.12.
test-rescript - 2.4.13.
test-rescript-watch - 2.4.14.
test-integration - 2.4.15.
test-integration-verbose - 2.4.16.
test-security - 2.4.17.
test-pentest - 2.4.18.
test-fuzz COMPONENT DURATION - 2.4.19.
test-coverage - 2.4.20.
test-coverage-view - 2.4.21.
test-bench - 2.4.22.
test-bench-criterion - 2.4.23.
test-mutate - 2.4.24.
test-property - 2.4.25.
test-e2e - 2.4.26.
test-smoke - 2.4.27.
test-load - 2.4.28.
test-stress
- 2.4.1.
- 2.5. 🎨 Linting & Formatting Recipes
- 2.5.1.
lint - 2.5.2.
lint-rust - 2.5.3.
lint-rust-all - 2.5.4.
lint-rust-pedantic - 2.5.5.
lint-elixir - 2.5.6.
lint-elixir-all - 2.5.7.
lint-rescript - 2.5.8.
lint-rescript-fix - 2.5.9.
lint-shell - 2.5.10.
lint-shell-strict - 2.5.11.
lint-yaml - 2.5.12.
lint-yaml-strict - 2.5.13.
lint-docker - 2.5.14.
lint-markdown - 2.5.15.
lint-markdown-fix - 2.5.16.
lint-json - 2.5.17.
lint-toml - 2.5.18.
format - 2.5.19.
format-rust - 2.5.20.
format-rust-check - 2.5.21.
format-elixir - 2.5.22.
format-elixir-check - 2.5.23.
format-rescript - 2.5.24.
format-toml - 2.5.25.
format-all - 2.5.26.
format-check
- 2.5.1.
- 2.6. 🔒 Security Recipes
- 2.6.1.
security - 2.6.2.
security-audit - 2.6.3.
security-audit-fix - 2.6.4.
security-secrets - 2.6.5.
security-secrets-deep - 2.6.6.
security-pentest - 2.6.7.
security-deps-check - 2.6.8.
security-sast - 2.6.9.
security-dast - 2.6.10.
security-sbom - 2.6.11.
security-verify-signatures - 2.6.12.
security-container-scan - 2.6.13.
security-container-bench - 2.6.14.
security-cve-check
- 2.6.1.
- 2.7. 📦 Installation & Deployment Recipes
- 2.7.1.
install - 2.7.2.
install-core - 2.7.3.
install-cli - 2.7.4.
install-cli-system - 2.7.5.
uninstall-cli-system - 2.7.6.
install-office-addin - 2.7.7.
install-completions - 2.7.8.
install-completions-bash - 2.7.9.
install-completions-zsh - 2.7.10.
install-completions-fish - 2.7.11.
deploy-prod - 2.7.12.
deploy-staging - 2.7.13.
deploy-website-gh - 2.7.14.
deploy-website-netlify
- 2.7.1.
- 2.8. 💾 Database Recipes
- 2.9. 🔧 Development Recipes
- 2.10. 📚 Documentation Recipes
- 2.11. 🚀 Release Recipes
- 2.11.1.
release VERSION - 2.11.2.
release-patch - 2.11.3.
release-minor - 2.11.4.
release-major - 2.11.5.
release-package - 2.11.6.
release-package-linux - 2.11.7.
release-package-macos - 2.11.8.
release-package-windows - 2.11.9.
release-verify VERSION - 2.11.10.
release-sign VERSION - 2.11.11.
release-upload VERSION - 2.11.12.
release-github VERSION
- 2.11.1.
- 2.12. 📊 Monitoring & Observability Recipes
- 2.13. 🧹 Cleanup Recipes
- 2.14. 📈 Statistics & Reporting Recipes
- 2.15. 🔬 CI/CD Recipes
- 2.16. 🌐 Website Recipes
- 2.17. 🔧 Utility Recipes
- 2.18. 🎯 Aliases & Shortcuts
- 3. Common Workflows
- 4. Configuration
- 5. Tips & Tricks
- 6. Troubleshooting
- 7. Appendix
- 8. Index
This cookbook provides comprehensive documentation for all available just recipes in the Academic Workflow Suite. The project uses Just, a modern command runner similar to Make but with better ergonomics.
# List all available recipes
just --list
# Run the interactive chooser
just
# Get help for a specific recipe
just help-recipe <recipe-name>
# Run a recipe
just <recipe-name>To use these recipes, you need to have just installed:
# macOS
brew install just
# Linux (cargo)
cargo install just
# Arch Linux
pacman -S just
# Ubuntu/Debian
curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to /usr/local/bin-
🏗️ Build operations
-
🐳 Docker operations
-
🧪 Testing operations
-
🎨 Linting and formatting
-
🔒 Security operations
-
📦 Installation and deployment
-
💾 Database operations
-
🔧 Development operations
-
📚 Documentation operations
-
🚀 Release operations
-
📊 Monitoring and observability
-
🧹 Cleanup operations
-
📈 Statistics and reporting
-
🔬 CI/CD operations
-
🌐 Website operations
-
🔧 Utility operations
-
🎯 Aliases and shortcuts
Display a list of all available recipes.
just helpOutput: List of all recipes with their descriptions.
Show detailed help for a specific recipe.
just help-recipe buildParameters:
-
RECIPE- Name of the recipe to show help for
Build all components of the project.
just buildDependencies: build-core, build-ai-jail, build-backend, build-office-addin, build-cli, build-shared, build-monitoring
Time: ~5-10 minutes
Clean and build all components from scratch.
just build-allDependencies: clean, build
Build all components in release mode with optimizations.
just build-releaseDependencies: build-core-release, build-ai-jail-release, build-backend-release, build-cli-release, build-shared-release
Note: This produces optimized binaries suitable for production.
Build all components in debug mode with debug symbols.
just build-debugDependencies: build-core-debug, build-ai-jail-debug, build-backend-debug, build-cli-debug, build-shared-debug
Build the Rust core engine in release mode.
just build-coreLocation: components/core
Output: components/core/target/release/core
Build the core engine in debug mode.
just build-core-debugOutput: components/core/target/debug/core
Build the core engine in release mode with all optimizations and locked dependencies.
just build-core-releaseFlags: --release --locked
Build the AI jail container (Rust + Docker).
just build-ai-jailSteps:
1. Builds Rust binary with cargo build --release
2. Builds Docker image with tag aws-ai-jail:latest
Build the Elixir/Phoenix backend.
just build-backendSteps:
1. Fetches dependencies with mix deps.get
2. Compiles in production mode with MIX_ENV=prod mix compile
Build the ReScript Office add-in.
just build-office-addinSteps:
1. Installs npm dependencies
2. Runs npm run build
Cross-compile for all platforms (Linux, macOS, Windows).
just build-cross-allDependencies: build-cross-linux, build-cross-macos, build-cross-windows
Note: Requires cross-compilation toolchains to be installed.
Cross-compile for Linux x86_64.
just build-cross-linuxTarget: x86_64-unknown-linux-gnu
Cross-compile for macOS x86_64.
just build-cross-macosTarget: x86_64-apple-darwin
Cross-compile for Windows x86_64.
just build-cross-windowsTarget: x86_64-pc-windows-gnu
Build all Docker images.
just docker-buildImages built: - aws-core - aws-backend - aws-ai-jail - aws-nginx
Build all Docker images without using cache.
just docker-build-no-cacheUse case: When you need a clean build or dependencies have changed.
Start the development environment using Docker Compose.
just docker-dev
# or
just devCompose files:
- docker-compose.yml
- docker-compose.dev.yml
Services started: - PostgreSQL - Redis - Core Engine - Backend Service - AI Jail - Nginx
Start the production environment.
just docker-prodCompose files:
- docker-compose.yml
- docker-compose.prod.yml
Restart the development environment.
just docker-restartSteps: 1. Stops all services 2. Starts all services
Run tests in Docker containers.
just docker-testCompose files:
- docker-compose.yml
- docker-compose.test.yml
Execute a command in a running service container.
just docker-exec core "ls -la"
just docker-exec backend "mix ecto.migrate"Parameters:
-
SERVICE- Name of the service (core, backend, postgres, redis, etc.) -
CMD- Command to execute
Open an interactive shell in the Core Engine container.
just docker-shell-coreOpen an interactive shell in the Backend Service container.
just docker-shell-backendOpen a psql shell in the PostgreSQL container.
just docker-shell-postgresReset the database in Docker (WARNING: Deletes all data).
just docker-db-resetBackup the PostgreSQL database.
just docker-db-backupOutput: backups/postgres/backup_YYYYMMDD_HHMMSS.sql.gz
Restore PostgreSQL database from a backup file.
just docker-db-restore backups/postgres/backup_20231201_120000.sql.gzParameters:
-
BACKUP_FILE- Path to the backup file
Reset all Docker data (WARNING: Deletes all data).
just docker-resetConfirmation required.
Clean up all Docker volumes (WARNING: Deletes data).
just docker-clean-volumesClean up everything Docker-related (WARNING: Deletes all data).
just docker-clean-allOpen Prometheus dashboard at http://localhost:9090.
just docker-prometheusInspect a Docker container’s configuration.
just docker-inspect coreParameters:
-
CONTAINER- Name of the container to inspect
Run all tests (unit, integration, security).
just testDependencies: test-unit, test-integration, test-security
Time: ~5-15 minutes
Run all tests with coverage reports.
just test-allDependencies: test-coverage, test-integration, test-security
Run all unit tests (Rust, Elixir, ReScript).
just test-unitDependencies: test-rust, test-elixir, test-rescript
Run Rust tests for all Rust components.
just test-rustComponents tested: - Core Engine - AI Jail - Shared Libraries - CLI
Run Rust tests in release mode.
just test-rust-releaseUse case: Testing release-optimized code
Run Rust tests with verbose output (prints println! statements).
just test-rust-verboseRun Rust tests single-threaded (useful for debugging).
just test-rust-singleRun a specific Rust test.
just test-rust-specific test_authenticationParameters:
-
TEST- Name of the test function or module
Run a specific Elixir test file.
just test-elixir-specific test/auth/user_test.exsParameters:
-
TEST- Path to the test file
Run ReScript tests in watch mode.
just test-rescript-watchUse case: Development with auto-rerunning tests
Run integration tests.
just test-integrationLocation: tests/benchmarks/integration_bench.sh
Run integration tests with verbose output.
just test-integration-verboseRun security tests.
just test-securityTests: - Dependency audits - Container escape tests - Network isolation verification
Run penetration tests.
just test-pentestTests: - SQL injection tests - XSS tests
|
Warning
|
Only run on authorized systems. |
Run fuzzing tests on a component.
just test-fuzz core 5mParameters:
-
COMPONENT- Name of the component (core, ai-jail, etc.) -
DURATION- Duration to run fuzzing (default: "1m")
Note: Requires cargo-fuzz to be installed.
Run tests with coverage reports.
just test-coverageOutput:
- components/core/target/coverage/index.html (Rust coverage)
- components/backend/cover/ (Elixir coverage)
Run criterion benchmarks (detailed performance testing).
just test-bench-criterionRun mutation testing.
just test-mutateNote: Requires cargo-mutants to be installed.
Run property-based tests.
just test-propertyNote: Runs tests with proptest feature enabled.
Run all linters.
just lintDependencies: lint-rust, lint-elixir, lint-rescript, lint-shell, lint-yaml, lint-docker, lint-markdown
Lint Rust code (all targets including tests, benches, examples).
just lint-rust-allLint Rust code with pedantic clippy lints.
just lint-rust-pedanticFlags: -W clippy::pedantic
Lint Elixir code.
just lint-elixirTools: - mix format --check-formatted - mix credo --strict
Lint Elixir code with all checks including dialyzer.
just lint-elixir-allNote: Dialyzer takes longer to run.
Lint shell scripts with strict mode.
just lint-shell-strictFlags: -x (follow sources)
Format all code.
just formatDependencies: format-rust, format-elixir, format-rescript, format-toml
Check Elixir formatting without modifying files.
just format-elixir-checkFormat all code and auto-fix linting issues.
just format-allDependencies: format, lint-markdown-fix, lint-rescript-fix
Run all security checks.
just securityDependencies: security-audit, security-secrets, security-pentest, security-deps-check
Run security audits for all dependency managers.
just security-auditTools: - cargo audit (Rust) - mix hex.audit (Elixir) - npm audit (Node.js)
Fix security vulnerabilities automatically where possible.
just security-audit-fixScan for secrets in the codebase.
just security-secretsLocation: security/audit-scripts/secret-scan.sh
Deep scan for secrets using trufflehog.
just security-secrets-deepNote: Requires trufflehog to be installed.
Run penetration tests.
just security-pentestTests: - SQL injection - XSS attacks
|
Warning
|
Only run on authorized systems. |
Check for outdated dependencies with known vulnerabilities.
just security-deps-checkTools: - cargo outdated - mix hex.outdated - npm outdated
Run Static Application Security Testing.
just security-sastTools: - cargo geiger (unsafe Rust usage) - Custom SAST scripts
Generate Software Bill of Materials.
just security-sbomOutput: sbom.json
Note: Requires cargo-sbom to be installed.
Scan containers for vulnerabilities.
just security-container-scanTool: docker scan
Run container security benchmark with Trivy.
just security-container-benchNote: Requires Trivy to be available.
Install all components.
just installDependencies: install-core, install-cli, install-office-addin
Install the CLI tool to user’s cargo bin.
just install-cliInstallation location: ~/.cargo/bin/aws
Install the CLI tool system-wide (requires sudo).
just install-cli-systemInstallation location: /usr/local/bin/aws
Uninstall the CLI tool from system (requires sudo).
just uninstall-cli-systemGenerate shell completions for the CLI.
just install-completionsOutput: cli/completions/
Install bash completions system-wide (requires sudo).
just install-completions-bashInstallation location: /etc/bash_completion.d/
Install zsh completions to user directory.
just install-completions-zshInstallation location: ~/.zsh/completion/
Install fish completions to user directory.
just install-completions-fishInstallation location: ~/.config/fish/completions/
Deploy to production environment.
just deploy-prodSteps: 1. Build in release mode 2. Run tests 3. Build Docker images without cache 4. Deploy using deployment script
Note: Requires production credentials.
Restore databases from a backup file.
just db-restore backups/backup_20231201.tar.gzParameters:
-
BACKUP_FILE- Path to the backup file
Create a new database migration.
just db-migration-create add_user_preferencesParameters:
-
NAME- Name of the migration
Output: New migration file in components/backend/priv/repo/migrations/
Rollback database to a specific version.
just db-rollback-to 20231201120000Parameters:
-
VERSION- Migration version timestamp
Show database migration status.
just db-migration-statusOutput: List of migrations with their status (up/down)
Seed the database with sample data.
just db-seedScript: components/backend/priv/repo/seeds.exs
Watch Rust files and rebuild/test on changes.
just dev-watch-rustNote: Requires cargo-watch to be installed.
Watch all files and rebuild on changes.
just dev-watchDependencies: dev-watch-rust, dev-watch-rescript
Note: Run in separate terminals as they both watch in foreground.
Start a development shell with Nix.
just dev-shellNote: Requires Nix with flakes enabled.
Update dependencies for all components.
just dev-deps-updateUpdates: - Cargo dependencies (Rust) - Mix dependencies (Elixir) - NPM dependencies (Node.js)
Check that all required development tools are installed.
just dev-deps-checkChecks: - Rust (rustc) - Elixir - Node.js - Docker - Just
Setup development environment.
just dev-setupSteps: 1. Install Rust components (clippy, rustfmt) 2. Install Cargo tools (audit, watch, tarpaulin, outdated) 3. Install NPM dependencies
Generate all documentation.
just docsDependencies: docs-rust, docs-elixir, docs-website
Create a new release.
just release 1.2.3Parameters:
-
VERSION- Semantic version number (e.g., 1.2.3)
Script: release/scripts/release.sh
Package for all platforms.
just release-packageScript: release/scripts/package.sh --all
Verify release artifacts.
just release-verify 1.2.3Parameters:
-
VERSION- Version to verify
Script: release/verify/verify_release.sh
Sign release artifacts.
just release-sign 1.2.3Parameters:
-
VERSION- Version to sign
Note: Requires GPG key configuration.
Upload release artifacts to GitHub.
just release-upload 1.2.3Parameters:
-
VERSION- Version to upload
Note: Requires GitHub CLI (gh) and authentication.
Start monitoring stack.
just monitoring-upComponents: - Prometheus - Grafana - Jaeger
View logs for a specific service.
just logs-service backendParameters:
-
SERVICE- Name of the service
View last N lines of logs.
just logs-tail 500Parameters:
-
N- Number of lines (default: 100)
Run health check on all services.
just healthScript: scripts/management/health-check.sh
Check service status and system resources.
just statusOutput: - Service status from docker-compose ps - Resource usage from docker stats
Clean all build artifacts.
just cleanDependencies: clean-rust, clean-elixir, clean-rescript, clean-docker, clean-temp
Clean everything including caches and dependencies.
just clean-allDependencies: clean, clean-cache, clean-deps
Clean Rust build artifacts.
just clean-rustRemoves:
- target/ directories in all Rust components
Clean Elixir build artifacts.
just clean-elixirRemoves:
- _build/ directory
- deps/ directory
Clean ReScript build artifacts.
just clean-rescriptRemoves:
- node_modules/ directory
- dist/ directory
Clean temporary files.
just clean-tempRemoves:
- .log files
- .tmp files
- Backup files (*~)
- .DS_Store files
Clean build caches.
just clean-cacheRemoves: - Cargo registry cache - Cargo git checkouts
Clean dependencies.
just clean-depsRemoves:
- Elixir deps/
- Node.js node_modules/
Show project statistics.
just statsOutput: - Lines of code (tokei) - Git statistics - File counts
Show Git statistics.
just stats-gitOutput: - Total commits - Total contributors - Repository size - Top contributors
Show dependency statistics.
just stats-depsOutput: - Rust crate count - Elixir package count - NPM package count
Show test statistics.
just stats-testOutput: - Number of Rust tests - Number of Elixir tests - Number of ReScript tests
Show Docker statistics.
just stats-dockerOutput: - Disk usage - Container counts - Image counts - Volume counts
Run full CI pipeline locally.
just ciDependencies: ci-lint, ci-test, ci-build, ci-security
Time: ~15-30 minutes
Run pre-commit hooks.
just ci-pre-commitNote: Requires pre-commit to be installed.
Install website build dependencies.
just website-installInstalls: - html-minifier - clean-css-cli - uglify-js - imagemin-cli
Serve website in development mode.
just website-serveServe built website (alias for docs-serve-built).
just website-serve-builtOptimize website assets.
just website-optimizeOptimizes: - CSS (minification) - JavaScript (minification) - Images (optimization)
Run Lighthouse performance audit.
just website-lighthouseOutput: lighthouse-report.html
Show website statistics.
just website-statsOutput: - HTML file count - CSS file count - JS file count - Total size - Build size
Deploy website to GitHub Pages (alias for deploy-website-gh).
just website-deploy-ghValidate RSR (Rust Safety Rules) compliance.
just rsr-validateChecks:
- Type safety
- Memory safety
- Documentation completeness
- .well-known files
- Build system
- TPCF compliance
- Test coverage
Show environment variables.
just env-showFilters: RUST*, CARGO*, MIX*, NODE*, DOCKER*
Update all development tools.
just tools-updateUpdates: - Rustup toolchain - Cargo-installed tools
Install all development tools.
just tools-installInstalls: - cargo-watch - cargo-audit - cargo-tarpaulin - cargo-outdated - cargo-edit - cargo-deny - cargo-geiger - cargo-sbom
Profile an application component.
just profile coreParameters:
-
COMPONENT- Name of the component to profile
Tool: cargo flamegraph
Note: Requires cargo-flamegraph to be installed.
Run quick checks (fast CI).
just quickDependencies: format-check, lint, test-unit
Time: ~3-5 minutes
Run full checks (complete CI).
just fullDependencies: lint, test, build
Time: ~15-30 minutes
Restore from a backup file.
just restore backups/backup_20231201.tar.gzParameters:
-
BACKUP_FILE- Path to the backup file
Initialize project for a new contributor.
just initSteps:
1. Run dev-setup
2. Build all components
3. Run all tests
4. Display next steps
Time: ~10-20 minutes
Show version information for all tools.
just versionShows versions of: - Project - Rust - Cargo - Elixir - Node.js - Docker - Docker Compose - Just
Generate a project report.
just reportOutput: PROJECT_REPORT.md
Contents: - Project statistics - Code metrics - Git statistics
These are convenient single-letter aliases for common commands:
| Alias | Recipe | Description |
|---|---|---|
|
|
Build all components |
|
|
Run all tests |
|
|
Run all linters |
|
|
Format all code |
|
|
Clean all build artifacts |
|
|
Start Docker development environment |
|
|
Stop Docker development environment |
|
|
Restart Docker development environment |
|
|
View Docker logs |
|
|
Show Docker service status |
|
|
Install all components |
|
|
Uninstall CLI from system |
|
|
Show version information |
|
|
Show help message |
|
|
Show project statistics |
|
|
Run quick checks |
|
|
Run CI pipeline locally |
|
|
Start development environment |
|
|
Stop development environment |
|
|
Restart development environment |
# Clone the repository
git clone https://github.com/Hyperpolymath/academic-workflow-suite.git
cd academic-workflow-suite
# Initialize the project
just init
# Start development environment
just dev
# In another terminal, run tests
just test# Start development environment
just up
# Watch for changes and auto-rebuild
just dev-watch-rust # In one terminal
just dev-watch-rescript # In another terminal
# Make changes to code...
# Run quick checks before committing
just quick
# Or run full checks
just full# Format all code
just format
# Run linters
just lint
# Run tests
just test
# If everything passes, commit
git add .
git commit -m "Your commit message"# Run full CI locally
just ci
# Create release
just release 1.2.3
# Package for all platforms
just release-package
# Verify release artifacts
just release-verify 1.2.3
# Sign release
just release-sign 1.2.3
# Create GitHub release
just release-github 1.2.3
# Upload artifacts
just release-upload 1.2.3# Start development environment
just dev
# View logs
just logs
# Or view logs for specific service
just logs-service backend
# Open shell in container
just docker-shell-core
# Run health check
just health-verbose
# Check service status
just statusThe Justfile uses the following environment variables (loaded from .env if present):
-
DOCKER_COMPOSE- Docker Compose command (default: "docker-compose") -
CLI_BINARY_NAME- CLI binary name (default: "aws") -
CLI_INSTALL_PATH- CLI installation path (default: "/usr/local/bin") -
WEBSITE_BUILD_DIR- Website build directory (default: "website/dist")
Run just without arguments to get an interactive chooser (if fzf is installed):
justInstall shell completions for better tab completion:
# For bash
just install-completions-bash
# For zsh
just install-completions-zsh
# For fish
just install-completions-fish# List all recipes
just --list
# List recipes with descriptions
just --list --list-heading $'Available recipes:\n'
# Search for specific recipes
just --list | grep docker# Show recipe source
just --show build
# Show all recipes in a category
just --list | grep "^docker-"# Run multiple recipes sequentially
just clean build test
# Run recipes with dependencies
just full # Runs lint, test, and build$ just biuld
error: Justfile does not contain recipe `biuld`.
Did you mean `build`?Solution: Check recipe spelling with just --list
$ just docker-up
ERROR: Couldn't connect to Docker daemonSolutions:
- Add user to docker group: sudo usermod -aG docker $USER
- Restart shell or log out/in
- Start Docker daemon: sudo systemctl start docker
$ just build
cargo: command not foundSolution: Install Rust: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
$ just build-backend
mix: command not foundSolution: Install Elixir: https://elixir-lang.org/install.html
$ just build-office-addin
npm: command not foundSolution: Install Node.js: https://nodejs.org/
For debugging Justfile issues:
# Show detailed execution
just --verbose --dry-run <recipe>
# Show Justfile evaluation
just --evaluateIf you encounter issues:
-
Check the cookbook: This document
-
Check recipe documentation:
just help-recipe <recipe> -
Check logs:
just logs -
Check service status:
just status -
Run health check:
just health-verbose -
Check project documentation:
README.md,CONTRIBUTING.md -
Ask for help: Create an issue on GitHub
| Recipe Count | Description |
|---|---|
50+ |
Build recipes |
60+ |
Docker recipes |
40+ |
Test recipes |
30+ |
Linting & formatting recipes |
20+ |
Security recipes |
20+ |
Installation & deployment recipes |
15+ |
Database recipes |
15+ |
Development recipes |
15+ |
Documentation recipes |
15+ |
Release recipes |
10+ |
Monitoring recipes |
15+ |
Cleanup recipes |
10+ |
Statistics recipes |
10+ |
CI/CD recipes |
10+ |
Website recipes |
20+ |
Utility recipes |
20+ |
Aliases |
300+ |
Total recipes |
Required tools:
-
Rust (rustc, cargo)
-
Elixir (elixir, mix)
-
Node.js (node, npm)
-
Docker (docker, docker-compose)
-
Just (just)
-
Git
Optional tools for enhanced functionality:
-
cargo-watch - File watching for Rust
-
cargo-audit - Security auditing
-
cargo-tarpaulin - Code coverage
-
cargo-outdated - Dependency updates
-
cargo-edit - Dependency management
-
cargo-deny - Dependency graph analysis
-
cargo-geiger - Unsafe code detection
-
cargo-sbom - SBOM generation
-
cargo-flamegraph - Performance profiling
-
shellcheck - Shell script linting
-
yamllint - YAML linting
-
hadolint - Dockerfile linting
-
markdownlint - Markdown linting
-
pre-commit - Git hooks
-
tokei - Code statistics
-
git-cliff - Changelog generation
-
gh - GitHub CLI
-
netlify - Netlify CLI
-
trufflehog - Secret scanning
-
trivy - Container scanning
-
Just Documentation: https://just.systems/
-
Rust Documentation: https://doc.rust-lang.org/
-
Elixir Documentation: https://elixir-lang.org/docs.html
-
Docker Documentation: https://docs.docker.com/
-
Project README: https://github.com/Hyperpolymath/academic-workflow-suite/blob/main/README.md
This cookbook is part of the Academic Workflow Suite project and is licensed under the same terms as the project (GNU Affero General Public License v3.0).
To contribute to this cookbook:
-
Fork the repository
-
Make your changes
-
Submit a pull request
See CONTRIBUTING.md for detailed guidelines.