Troubleshooting Guide

Common issues and solutions when using Asantiya for application deployment.

Quick Diagnostics

Before diving into specific issues, run these diagnostic commands:

# Check system health
asantiya doctor
 
# Validate configuration
asantiya config validate
 
# Check application status
asantiya status
 
# View recent logs
asantiya logs --tail 50

Installation Issues

Command Not Found: asantiya

Problem: asantiya: command not found

Solutions:

1. Check installation location:

   pip show asantiya

2. Add to PATH (Linux/macOS):

   export PATH="$HOME/.local/bin:$PATH"
   echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

3. Reinstall with user flag:

   pip install --user asantiya

4. Use full path:

   ~/.local/bin/asantiya --version

Python Version Issues

Problem: Python version conflicts or missing Python

Solutions:

1. Check Python version:

   python --version
   python3 --version

2. Install Python 3.10+:

   # Ubuntu/Debian
   sudo apt update
   sudo apt install python3.10 python3.10-pip
    
   # macOS with Homebrew
   brew install python@3.10
    
   # Windows
   # Download from python.org

3. Use virtual environment:

   python3 -m venv asantiya-env
   source asantiya-env/bin/activate  # Linux/macOS
   # or
   asantiya-env\Scripts\activate     # Windows
   pip install asantiya

Docker Issues

Docker Not Found

Problem: Docker not found or Cannot connect to Docker daemon

Solutions:

1. Install Docker:

   # Ubuntu/Debian
   sudo apt update
   sudo apt install docker.io
   sudo systemctl start docker
   sudo systemctl enable docker
    
   # macOS/Windows
   # Install Docker Desktop

2. Start Docker service:

   # Linux
   sudo systemctl start docker
    
   # macOS/Windows
   # Start Docker Desktop application

3. Add user to docker group (Linux):

   sudo usermod -aG docker $USER
   # Log out and log back in

4. Test Docker:

   docker --version
   docker run hello-world

Permission Denied

Problem: Permission denied while trying to connect to Docker daemon

Solutions:

1. Add user to docker group (Linux):

   sudo usermod -aG docker $USER
   newgrp docker

2. Use sudo (temporary solution):

   sudo asantiya deploy

3. Check Docker socket permissions:

   ls -la /var/run/docker.sock
   sudo chmod 666 /var/run/docker.sock

Docker Build Failures

Problem: Docker build fails with various errors

Solutions:

1. Check Dockerfile syntax:

   docker build -t test-image .

2. Clear Docker cache:

   docker system prune -a

3. Check disk space:

   df -h
   docker system df

4. Build with verbose output:

   asantiya deploy --verbose

Configuration Issues

Invalid YAML Syntax

Problem: YAML syntax error or Invalid configuration

Solutions:

1. Validate YAML syntax:

   asantiya config validate

2. Check indentation:

   # Correct (2 spaces)
   service: myapp
   image: myapp
    
   # Incorrect (tabs or wrong spacing)
   service: myapp
   	image: myapp

3. Use YAML validator:

   # Online: yamlchecker.com
   # CLI: yamllint deploy.yaml

Missing Required Fields

Problem: Missing required field: service

Solutions:

1. Check required fields:

   service: myapp      # Required
   image: myapp        # Required
   server: 127.0.0.1  # Required

2. Use asantiya init:

   asantiya init

Environment Variable Issues

Problem: Environment variables not being set correctly

Solutions:

1. Check .env file:

   cat .env

2. Use proper syntax:

   env:
     - NODE_ENV=production
     - API_KEY=${API_KEY}  # From .env file

3. Export variables:

   export API_KEY=your-key
   asantiya deploy

Deployment Issues

Port Already in Use

Problem: Port 8080 is already in use

Solutions:

1. Check what’s using the port:

   # Linux/macOS
   lsof -i :8080
    
   # Windows
   netstat -ano | findstr :8080

2. Use a different port:

   port: "8081:3000"

3. Stop conflicting service:

   # Find and stop the process
   sudo kill -9 <PID>

Connection Refused

Problem: Connection refused when accessing application

Solutions:

1. Check if application is running:

   asantiya status
   docker ps

2. Check application logs:

   asantiya logs

3. Verify port mapping:

   port: "8080:3000"  # Host:Container

4. Check firewall:

   # Linux
   sudo ufw status
   sudo ufw allow 8080

Application Won’t Start

Problem: Application container exits immediately

Solutions:

1. Check container logs:

   asantiya logs
   docker logs <container-name>

2. Check Dockerfile CMD:

   # Make sure CMD is correct
   CMD ["npm", "start"]
   # or
   CMD ["python", "app.py"]

3. Test container locally:

   docker build -t test-app .
   docker run -p 8080:3000 test-app

4. Check environment variables:

   asantiya config show

Accessory Issues

Database Connection Failed

Problem: Application can’t connect to database

Solutions:

1. Check database status:

   asantiya accessory status postgres

2. Check database logs:

   asantiya accessory logs postgres

3. Verify connection string:

   env:
     - DATABASE_URL=postgres://user:password@postgres:5432/myapp

4. Check network connectivity:

   docker network ls
   docker network inspect asantiya

Accessory Won’t Start

Problem: Accessory service fails to start

Solutions:

1. Check accessory configuration:

   accessories:
     postgres:
       service: postgres
       image: postgres:15-alpine
       port: "5432:5432"
       env:
         - POSTGRES_DB=myapp
         - POSTGRES_USER=user
         - POSTGRES_PASSWORD=password

2. Check for port conflicts:

   lsof -i :5432

3. Remove and redeploy:

   asantiya accessory remove postgres
   asantiya accessory deploy postgres

Network Issues

SSH Connection Failed

Problem: Can’t connect to remote server via SSH

Solutions:

1. Test SSH connection:

   ssh user@your-server.com

2. Check SSH key:

   ssh-add -l
   ssh-copy-id user@your-server.com

3. Use SSH config:

   # ~/.ssh/config
   Host myserver
     HostName your-server.com
     User user
     Port 22
     IdentityFile ~/.ssh/id_rsa

4. Check server configuration:

   server: myserver  # Use SSH config alias

Remote Build Failures

Problem: Remote Docker build fails

Solutions:

1. Check remote Docker:

   ssh user@server "docker --version"

2. Test remote connection:

   ssh user@server "docker run hello-world"

3. Check remote builder config:

   builder:
     local: false
     remote: ssh://docker@builder-server

Performance Issues

Slow Builds

Problem: Docker builds are very slow

Solutions:

1. Use .dockerignore:

   node_modules
   .git
   *.log
   .env

2. Optimize Dockerfile:

   # Use multi-stage builds
   FROM node:18-alpine as build
   WORKDIR /app
   COPY package*.json ./
   RUN npm install
   COPY . .
   RUN npm run build
    
   FROM nginx:alpine
   COPY --from=build /app/build /usr/share/nginx/html

3. Use build cache:

   docker build --cache-from myapp:latest -t myapp .

High Memory Usage

Problem: Containers using too much memory

Solutions:

1. Set memory limits:

   accessories:
     postgres:
       service: postgres
       image: postgres:15-alpine
       options:
         memory: 512m
         cpus: 0.5

2. Monitor resource usage:

   docker stats

3. Optimize application:

   • Reduce memory footprint
   • Use smaller base images
   • Implement proper garbage collection

Logging and Debugging

Enable Verbose Logging

# Enable verbose output
asantiya --verbose deploy
 
# Set environment variable
export ASANTIYA_VERBOSE=true
asantiya deploy

Debug Mode

# Dry run to see what would happen
asantiya deploy --dry-run
 
# Test configuration
asantiya config test

Log Analysis

# Follow logs in real-time
asantiya logs --follow
 
# Show logs with timestamps
asantiya logs --timestamps
 
# Show last 100 lines
asantiya logs --tail 100
 
# Show logs since specific time
asantiya logs --since 2h

Getting Help

Self-Help Resources

1. Check documentation:

   • Configuration Reference
   • CLI Reference
   • Examples

2. Run diagnostics:

   asantiya doctor
   asantiya config validate
   asantiya status

3. Check logs:

   asantiya logs
   asantiya accessory logs

Community Support

1. GitHub Issues:

   • Report bugs 
   • Request features 
   • Ask questions 

2. Search existing issues:

   • Check if your issue has been reported
   • Look for similar problems and solutions

3. Provide information: When reporting issues, include:

   • Asantiya version: asantiya --version
   • Configuration file (remove secrets)
   • Error messages and logs
   • System information: asantiya doctor

Professional Support

For enterprise support or complex issues:

1. Contact maintainers through GitHub
2. Check documentation for enterprise features
3. Consider consulting for custom deployments

Prevention Tips

Best Practices

1. Use version control for configuration files
2. Test locally before deploying to production
3. Use environment-specific configurations
4. Monitor resources and set appropriate limits
5. Keep dependencies updated
6. Use health checks in your applications
7. Implement proper logging
8. Backup important data

Regular Maintenance

# Clean up unused resources
docker system prune -a
 
# Update Asantiya
pip install --upgrade asantiya
 
# Check for security updates
docker scan myapp:latest

Still having issues? Check out our Examples for working configurations or join the community  for help.