Step 8: Archetect (Required)

Time: 3 minutes
Purpose: Install Archetect for creating projects from company-approved templates

Company Requirement

Archetect is required for creating new company projects. All projects must be created from approved templates to ensure consistency and compliance.

What is Archetect?

Archetect is a project scaffolding tool that creates new projects from predefined templates. The company uses it to ensure all projects:

• Follow established architecture patterns
• Include required security configurations
• Have proper CI/CD pipeline setup
• Include necessary documentation
• Meet compliance requirements

Installation

Installation: Follow the official guide at Archetect Installation

Platform	Installation Method	Official Documentation
macOS	Homebrew or Binary	archetect.github.io/docs
Windows	Binary Download	GitHub Releases
Linux	Binary or Cargo	archetect.github.io/docs

Quick Install Commands

# macOS (Homebrew)
brew tap archetect/tap
brew install archetect

# Windows (PowerShell 7) - Download and install manually
# Download from: https://github.com/archetect/archetect/releases/latest

# Linux (Ubuntu/Debian) - Binary install
curl -L https://github.com/archetect/archetect/releases/latest/download/archetect-linux -o archetect
chmod +x archetect
sudo mv archetect /usr/local/bin/

# Any OS with Rust toolchain
cargo install archetect

Note: See Archetect Installation Guide for detailed platform-specific instructions.

Configuration

Step 1: Configure Company Template Repository

# Add company template repository
archetect catalog add company https://your-company-templates.git

# Alternative: If using internal Git server
archetect catalog add company git@company-git:templates/archetypes.git

# Verify catalog was added
archetect catalog list

Step 2: Authentication (If Required)

If templates are in private repositories:

# Configure Git credentials (if not already done)
git config --global credential.helper store

# Test access to template repository
git clone https://your-company-templates.git /tmp/test-templates
rm -rf /tmp/test-templates  # Clean up test

Step 3: Update Templates

# Update all template catalogs to get latest versions
archetect catalog update

# Update specific catalog
archetect catalog update company

Available Templates

List All Templates

# Show all available templates
archetect list

# Show templates from company catalog
archetect list company

# Search for specific templates
archetect search api
archetect search microservice

Common Company Templates

The following are typical templates your company might provide:

• company/microservice-java - Spring Boot microservice
• company/microservice-nodejs - Node.js microservice
• company/web-app-react - React web application
• company/web-app-nextjs - Next.js full-stack application
• company/api-gateway - API Gateway configuration
• company/data-pipeline - Data processing pipeline
• company/lambda-function - Serverless function

Creating Projects

Basic Project Creation

# Create project from template
archetect generate company/microservice-java my-new-service

# Follow interactive prompts for:
# - Service name
# - Description  
# - Package name
# - Database type
# - API style (REST, GraphQL, gRPC)
# - Authentication method
# - etc.

Advanced Project Creation

# Non-interactive mode with answers file
archetect generate company/microservice-java my-service --answers answers.yaml

# Specify specific template version
archetect generate company/microservice-java@v2.1.0 my-service

# Generate in specific directory
archetect generate company/web-app-react my-app --destination ./projects/

Example Answers File

Create answers.yaml for consistent project creation:

service_name: "user-management-service"
description: "Microservice for user management and authentication"
package_name: "com.company.users"
database_type: "postgresql"
api_style: "rest"
auth_method: "jwt"
team_name: "platform-team"
owner_email: "platform-team@company.com"

Verification

# Check Archetect version
archetect --version

# Verify company templates are available
archetect list company  # Should show company templates

# Test template generation (dry run)
archetect generate company/microservice-java test-service --dry-run

Full Test

Create a test project to verify everything works:

# Create test project
mkdir ~/temp-test && cd ~/temp-test
archetect generate company/microservice-java test-service

# Verify project structure
cd test-service
ls -la  # Should show generated project files

# Verify project builds (example for Java)
./mvnw clean compile  # Should compile successfully

# Clean up
cd ~ && rm -rf ~/temp-test

Troubleshooting

"archetect: command not found"

1. Check installation: Verify binary is in your PATH
2. Restart terminal: Close and reopen after installation
3. PATH issues: Ensure installation directory is in PATH

"Catalog not found" or "Template not found"

1. Update catalogs: Run archetect catalog update
2. Check catalog URL: Verify company template repository URL is correct
3. Authentication: Ensure you have access to template repository
4. Network: Check VPN connection if required

Template generation fails

1. Permissions: Ensure you have write permissions in target directory
2. Dependencies: Some templates may require additional tools (Node.js, Java, etc.)
3. Answers: Check that all required template variables are provided
4. Template version: Try using a specific template version if latest fails

Git authentication issues

1. SSH keys: Ensure SSH keys are set up for company Git server
2. Credentials: Configure Git credential helper
3. VPN: Connect to company VPN if required
4. Firewall: Check if company Git server is accessible

Template is out of date

1. Update catalog: archetect catalog update company
2. Clear cache: Remove cached templates if available
3. Check version: Use specific template version with @version syntax

Project fails to build after generation

1. Dependencies: Ensure all required development tools are installed
2. Environment: Check environment variables are set correctly
3. Templates: Report issue to template maintainers
4. Documentation: Check generated project's README for specific setup steps

Need help?

• Run archetect --help for built-in documentation
• Check template-specific documentation in generated projects
• Contact DevOps team for template issues
• Reference company developer portal for template guidelines

Next Step

Step 10: IDE Setup (Final Step)