29 docs tagged with "engineering-handbook"

Authentication vs. authorization, JWT structure, OAuth2/OIDC flows, Azure Entra External ID (CIAM) claim mapping, role- and claims-based authorization, and common auth failure modes.

Installing and authenticating the Azure CLI, its command structure, output formatting and JMESPath queries, scripting patterns, and service-principal login for pipelines.

Storing secrets, keys, and certificates in Key Vault, access policies vs RBAC, managed identity access, Key Vault references in App Service, and the secret-caching gotcha that requires a full stop/start.

VNets and subnets in Azure, NSG rules, service endpoints vs private endpoints, App Service VNet integration, and how these combine to secure resources like Azure SQL.

How Azure role-based access control actually works — the scope hierarchy, role assignments, built-in roles, control-plane vs data-plane access, and diagnosing permission failures.

Blob storage fundamentals — containers, access tiers, authentication methods (connection strings, SAS tokens, managed identity), lifecycle management, and diagnosing access failures.

Complete reference for the Bash shell — navigation, file management, text processing, permissions, scripting, and troubleshooting, with examples drawn from real Traxs development workflows.

Continuous Integration and Deployment concepts, Azure DevOps pipeline structure, the self-hosted agent setup, environment-specific deploy targeting, and the real incident (TRA-195) that came from getting it wrong.

How DNS actually resolves a name to an address — recursive vs authoritative resolution, record types, TTLs, Azure DNS and private zones, split-brain DNS, email authentication records, and propagation.

Orchestrating multi-container local development with Docker Compose — anatomy of a compose file, a realistic API + SQL Server + Redis setup, environment variables, health checks, and troubleshooting.

What containers actually are, images vs containers, writing a Dockerfile, core commands, volumes, networking, and how this maps to OrbStack for local Traxs development.

Complete reference for Git — the working directory/staging/commit model, branching, merging, rebasing, remotes, undoing changes, and the Traxs branch-and-PR workflow.

Recovery procedures for Git — reflog workflows, undoing bad merges, force-push incident recovery, detached HEAD, recovering "lost" commits, and removing committed secrets from history.

JSON and YAML syntax, common gotchas in each, when to use which, and how they show up across Traxs — API payloads, appsettings.json, and Azure DevOps pipeline YAML.

Core Kubernetes concepts — pods, deployments, services, ingress, namespaces — and, just as importantly, when Kubernetes is the right tool versus when a simpler platform like App Service already covers the need.

Managing users and groups, systemd services in depth including writing a unit file, cron scheduling, log locations, and disk/resource monitoring on a Linux host.

The Linux operating system itself — distributions, the filesystem hierarchy standard, users and permissions at the OS level, processes and init systems, and package managers, distinct from shell command usage.

The difference between a load balancer and a reverse proxy, load balancing algorithms, health probes, SSL offload, Azure Application Gateway vs. Front Door, and WAF basics.

Tenants, app registrations, service principals vs managed identities, and the specific Entra configuration gotchas — AzureAd:Instance, managed identity SQL auth — that cause silent failures.

Miscellaneous command references, various commands such as migrations etc.

A systematic, layer-by-layer methodology for diagnosing network issues, the core toolkit (ping, traceroute, dig, curl, openssl, netstat/lsof, nc), and walkthroughs of common real-world scenarios.

The three pillars of observability, structured logging with Seq, App Service Log Stream, correlation IDs, and how the CORS-masks-500s pattern connects logs, symptoms, and root cause.

Organizing collections and environments, managing bearer-token auth, writing basic test scripts, and troubleshooting the most common causes of confusing Postman behavior.

REST principles, HTTP methods and idempotency, status codes, resource naming, pagination and versioning, and how these map onto the Traxs command/query API design conventions.

The right secret store for each context — local development, pipelines, and runtime application configuration — Bitwarden usage, rotation practices, and what never to do with a secret.

Complete reference for SSH — key generation, ssh-agent, the SSH config file, GitHub/Azure DevOps integration, port forwarding, and troubleshooting authentication failures.

How HTTPS actually secures a connection — PKI and certificate authorities, the TLS handshake, certificate validation, automated issuance with Let's Encrypt, and diagnosing certificate errors.

How network communication actually works — the OSI and TCP/IP models, IP addressing, subnetting and CIDR, ports, TCP vs UDP, NAT, routing, and how these map onto Azure networking.

What a VPN actually does, remote-access vs site-to-site VPNs, the major protocols, Azure VPN Gateway, and when a Traxs workflow actually needs one versus when it doesn't.