Asantiya – Bringing Ease to Your Deployment Workflow

Asantiya (Pashto: اسانتیا) isn't just a name – it embodies the spirit of the tool. In Pashto:

• asan (اسان) = easy
• asantiya (اسانتیا) = ease, comfort, convenience

This CLI tool makes deploying applications effortless, whether you're targeting local environments or remote servers.

✨ Why Asantiya?

• 🚀 Zero-Deploy-Friction: Automate deployments so you can focus on coding, not server setup
• 🌍 Environment Agnostic: Works seamlessly for both local testing and production environments
• 🐳 Docker-Powered: Ensures consistency across environments with containerization
• 👨‍💻 Developer-Friendly: Intuitive CLI commands with beautiful output and progress tracking
• 📝 Config-Driven: Control ports, images, and environments through simple YAML files
• 🔧 Highly Configurable: Support for multiple architectures, remote builds, and complex service dependencies
• 🛡️ Production Ready: Comprehensive error handling, logging, and validation

🚀 Quick Start

# Install Asantiya
pip install asantiya

# Initialize your project
asantiya init

# Deploy your application
asantiya deploy

📖 Table of Contents

• Installation
• Quick Start
• Configuration
• Commands
• Examples
• Development
• Contributing
• License

🛠️ Installation

From PyPI (Recommended)

pip install asantiya

From Source

git clone https://github.com/shahid-0/asantiya.git
cd asantiya
pip install -e .

Development Installation

git clone https://github.com/shahid-0/asantiya.git
cd asantiya
pip install -e ".[dev]"

🎯 Quick Start

1. Initialize Your Project

# Interactive setup
asantiya init

# Or use a template
asantiya init --template basic
asantiya init --template full
asantiya init --template minimal

2. Configure Your Application

Asantiya will create a deploy.yaml file with your configuration:

# Main application configuration
service: my-app
image: my-app:latest

# Port mappings (host:container)
app_ports: 8080:80

# Build configuration
builder:
  arch: amd64
  local: true

# Container services definitions
accessories:
  db:
    service: my-app-db
    image: postgres:13
    ports: 5432:5432
    env:
      POSTGRES_PASSWORD: "secure-password"
    volumes:
      - db_data:/var/lib/postgresql/data
    network: my-app-network

3. Deploy Your Application

# Deploy with confirmation
asantiya deploy

# Deploy without confirmation
asantiya deploy --force

# Deploy with custom config
asantiya deploy --config production.yaml

⚙️ Configuration

Configuration File Structure

The deploy.yaml file supports the following structure:

# Required fields
service: string              # Application service name
image: string               # Docker image name
app_ports: string           # Port mapping (host:container)

# Optional fields
environment:                # Environment variables
  KEY: value
volumes:                    # Volume mounts
  - host_path:container_path
network: string             # Docker network name

# Build configuration
builder:
  arch: amd64|arm64|armv7  # Target architecture
  local: boolean           # Local or remote build
  remote: string           # Remote Docker URL (if not local)
  dockerfile: string       # Dockerfile path
  build_args:              # Build arguments
    KEY: value

# Accessory services
accessories:
  service_name:
    service: string         # Container name
    image: string          # Docker image
    ports: string          # Port mapping
    env:                   # Environment variables
      KEY: value
    volumes:               # Volume mounts
      - host_path:container_path
    network: string        # Docker network
    depends_on:            # Service dependencies
      - other_service
    options:               # Container options
      restart: always|unless-stopped|on-failure|no

Environment Variables

Asantiya supports environment variable substitution in configuration files:

service: ${APP_NAME}
image: ${DOCKER_REGISTRY}/${APP_NAME}:${VERSION}

Required environment variables can be specified:

asantiya deploy --required-vars SERVER,APP_NAME,VERSION

📋 Commands

Main Commands

Command	Description
asantiya init	Initialize configuration files
asantiya deploy	Build and deploy application
asantiya app	Manage main application container
asantiya accessory	Manage accessory containers

Application Management

# Start application
asantiya app start

# Stop application
asantiya app stop

# Restart application
asantiya app restart

# Remove application
asantiya app remove

Accessory Management

# Start all accessories
asantiya accessory up

# Stop all accessories
asantiya accessory down

# List accessories
asantiya accessory ls

# View logs
asantiya accessory logs db

# Restart specific accessory
asantiya accessory restart db

# Reboot accessory (stop, remove, recreate)
asantiya accessory reboot db

Deployment Options

# Deploy with options
asantiya deploy --force --skip-build --skip-accessories

# Use custom configuration
asantiya deploy --config production.yaml

# Enable verbose output
asantiya deploy --verbose

💡 Examples

Basic Web Application

service: webapp
image: webapp:latest
app_ports: 8080:80
builder:
  arch: amd64
  local: true
accessories:
  db:
    service: webapp-db
    image: postgres:13
    ports: 5432:5432
    env:
      POSTGRES_DB: webapp
      POSTGRES_PASSWORD: secure-password
    volumes:
      - db_data:/var/lib/postgresql/data
    network: webapp-network

Microservices with Dependencies

service: api-gateway
image: api-gateway:latest
app_ports: 8080:80
builder:
  arch: amd64
  local: false
  remote: ssh://build@ci.example.com
accessories:
  auth-service:
    service: auth-service
    image: auth-service:latest
    ports: 3001:3000
    network: microservices-network
    depends_on: [redis, postgres]
  
  redis:
    service: redis
    image: redis:alpine
    ports: 6379:6379
    network: microservices-network
  
  postgres:
    service: postgres
    image: postgres:13
    ports: 5432:5432
    env:
      POSTGRES_PASSWORD: secure-password
    volumes:
      - postgres_data:/var/lib/postgresql/data
    network: microservices-network

Multi-Architecture Build

service: multiarch-app
image: multiarch-app:latest
app_ports: 8080:80
builder:
  arch: arm64
  local: false
  remote: ssh://build@arm-server.com
  build_args:
    BUILD_ENV: production

🧪 Development

Setting Up Development Environment

# Clone the repository
git clone https://github.com/shahid-0/asantiya.git
cd asantiya

# Install development dependencies
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

# Run tests
pytest

# Run linting
flake8 asantiya tests
black asantiya tests
isort asantiya tests

# Type checking
mypy asantiya

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=asantiya --cov-report=html

# Run specific test file
pytest tests/test_schemas.py

# Run with verbose output
pytest -v

Code Quality

The project uses several tools to maintain code quality:

• Black: Code formatting
• isort: Import sorting
• flake8: Linting
• mypy: Type checking
• pytest: Testing
• pre-commit: Git hooks

Project Structure

asantiya/
├── asantiya/                 # Main package
│   ├── accessories/          # Accessory management commands
│   ├── app/                  # Application management commands
│   ├── schemas/              # Pydantic models
│   ├── utils/                # Utility functions
│   ├── cli.py               # Main CLI interface
│   ├── deploy.py            # Deployment commands
│   ├── docker_manager.py    # Docker operations
│   ├── init.py              # Initialization commands
│   └── logger.py            # Logging configuration
├── tests/                   # Test suite
├── .github/workflows/       # CI/CD pipelines
├── docs/                    # Documentation
└── examples/                # Example configurations

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for your changes
5. Run the test suite (pytest)
6. Run code quality checks (pre-commit run --all-files)
7. Commit your changes (git commit -m 'Add amazing feature')
8. Push to the branch (git push origin feature/amazing-feature)
9. Open a Pull Request

Reporting Issues

Please report bugs and request features through GitHub Issues.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Docker for containerization
• Typer for CLI framework
• Rich for beautiful terminal output
• Pydantic for data validation
• Paramiko for SSH connections

📞 Support

• 📖 Documentation
• 🐛 Report Issues
• 💬 Discussions
• 📧 Email

---

Made with ❤️ by Shahid Khan