Skip to content

deployment.md

Latest commit

 

History

History
295 lines (202 loc) · 5.83 KB

deployment.md

File metadata and controls

295 lines (202 loc) · 5.83 KB

Deployment Guide

Overview

py_template is a Python library that can be deployed in various ways depending on your use case. This guide covers common deployment scenarios.

Package Distribution

Building the Package

# Install build tools
uv add --dev build

# Build the distribution packages
uv run python -m build

# This creates:
# - dist/py_template-0.1.0.tar.gz (source distribution)
# - dist/py_template-0.1.0-py3-none-any.whl (wheel)

Local Installation

# Install from local directory
pip install /path/to/py_template

# Install in editable mode (for development)
pip install -e /path/to/py_template

Private Package Repository

For proprietary software, you can use a private package repository:

Using PyPI Server (Self-hosted)

# Install pypiserver
pip install pypiserver

# Start server
pypi-server -p 8080 /path/to/packages

# Upload package
twine upload --repository-url http://localhost:8080 dist/*

# Install from private server
pip install --index-url http://localhost:8080/simple/ py_template

Using Artifactory or Nexus

Configure your .pypirc:

[distutils]
index-servers =
    private-repo

[private-repo]
repository: https://your-artifactory.com/repository/pypi/
username: your-username
password: your-password

Upload:

twine upload -r private-repo dist/*

Git-based Deployment

Direct Installation from Git

# Install from main branch
pip install git+https://github.com/your-org/py_template.git

# Install from specific tag
pip install git+https://github.com/your-org/py_template.git@v0.1.0

# Install from specific branch
pip install git+https://github.com/your-org/py_template.git@dev

Using requirements.txt

# requirements.txt
py_template @ git+https://github.com/your-org/py_template.git@v0.1.0

Using pyproject.toml

[project.dependencies]
py_template = { git = "https://github.com/your-org/py_template.git", tag = "v0.1.0" }

Environment Setup

Production Environment

# Install only production dependencies
uv sync --no-dev

# Or with pip
pip install -r requirements.txt

Environment Variables

Create a .env file based on .env.example:

cp .env.example .env
# Edit .env with your configuration

Docker Deployment (Optional)

While py_template is a library, you might want to containerize applications that use it:

Dockerfile Example

FROM python:3.12-slim

WORKDIR /app

# Install uv
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/

# Copy dependency files
COPY pyproject.toml uv.lock* ./

# Install dependencies
RUN uv sync --no-dev --frozen

# Copy application code
COPY . .

# Set Python path
ENV PYTHONPATH=/app/src

CMD ["python", "-m", "your_app"]

CI/CD Integration

GitHub Actions

The project includes pre-configured workflows:

Release Process

  1. Update version in src/py_template/version.py
  2. Update CHANGELOG.md
  3. Create a git tag: 
    git tag -a v0.1.0 -m "Release version 0.1.0"
git push origin v0.1.0
  4. Build and distribute the package

Version Management

Semantic Versioning

Follow semantic versioning (MAJOR.MINOR.PATCH):

  • MAJOR: Incompatible API changes
  • MINOR: Backward-compatible functionality additions
  • PATCH: Backward-compatible bug fixes

Version Bumping

# Manually update version in src/py_template/__version__.py
# Then commit and tag
git commit -am "Bump version to 0.2.0"
git tag -a v0.2.0 -m "Release version 0.2.0"
git push && git push --tags

Monitoring and Maintenance

Health Checks

For applications using py_template:

from py_template import __version__

def health_check():
    """Verify py_template is installed and working."""
    return {
        "status": "healthy",
        "py_template_version": __version__
    }

Dependency Updates

# Update dependencies
uv sync --upgrade

# Check for security vulnerabilities
uv run safety check

# Review and commit uv.lock
git add uv.lock
git commit -m "Update dependencies"

Rollback Procedures

Git-based Rollback

# Revert to previous version
pip install git+https://github.com/your-org/py_template.git@v0.0.9

Package Rollback

# Install specific version
pip install py_template==0.0.9

Security Considerations

  1. Private Repository: Keep your repository private since this is proprietary software
  2. Access Control: Limit access to the package repository
  3. Dependency Scanning: Regularly scan dependencies for vulnerabilities
  4. Code Signing: Consider signing your packages
  5. Secret Management: Never commit API keys or credentials

Support and Troubleshooting

Common Issues

Import Errors

# Ensure PYTHONPATH is set correctly
export PYTHONPATH=/path/to/installation/src

Dependency Conflicts

# Use virtual environment
uv venv
source .venv/bin/activate
uv sync

Getting Help

Backup and Recovery

Backup Strategy

  1. Source Code: Keep in version control (Git)
  2. Dependencies: Lock files (uv.lock) ensure reproducibility
  3. Configuration: Store .env.example in version control

Recovery

# Clone repository
git clone https://github.com/your-org/py_template.git
cd py_template

# Restore dependencies
uv sync

# Verify installation
uv run py_template info