activist-remote-dev

Activist Development Environment

Overview

The Activist Development Environment is a custom-built remote development solution designed to provide a cost-effective and efficient alternative to local Docker development and cloud-based development environments like GitHub Codespaces. Recognizing the resource-intensive nature of local Docker Desktop development and the higher costs associated with cloud-based alternatives, this project was created to offer a streamlined, remote development experience.

This environment leverages DigitalOcean droplets as remote development servers, managed through a combination of Terraform for infrastructure provisioning and Ansible for configuration management. The system is designed to be lightweight, secure, and easily reproducible, while maintaining the flexibility needed for modern web application development.

Key features of the environment include:

The environment is particularly well-suited for developers who:

By providing a remote development environment that balances performance, cost, and flexibility, this project aims to make development more accessible and efficient for individual developers and small teams working on the Activist application.

Features

Core Features

Development Tools

Security Features

Integration & Automation

Cross-Platform Support

Customization

Prerequisites

Required Software

API Keys and Credentials

System Requirements

Accounts

Network Requirements

Quick Start

Installation

  1. Install Required Tools:

    # Install Terraform
brew install terraform

# Install Ansible
brew install ansible

# Install DigitalOcean CLI
brew install doctl

  2. Configure DigitalOcean Access:

    # Authenticate with DigitalOcean
doctl auth init

# Add your SSH key to DigitalOcean
doctl compute ssh-key create <key-name> --public-key-file ~/.ssh/id_rsa.pub

Initial Setup

  1. Clone the Repository:

    git clone https://github.com/your-username/activist-dev-env.git
cd activist-dev-env

  2. Configure Environment Variables: Set the DO_TOKEN environment variable:

    export DO_TOKEN="your_digitalocean_api_token"

First Deployment

  1. Initialize Terraform:

    cd terraform/environments/dev
terraform init

  2. Create Infrastructure:

    terraform apply

  3. Deploy with Ansible:

    cd ../../ansible
ansible-playbook -i inventory/dev playbooks/deploy.yml

  4. Access Your Environment:

    # Get the droplet IP
DROPLET_IP=$(terraform output -raw droplet_ip)

# SSH into the droplet
ssh root@$DROPLET_IP

Next Steps

Project Structure

Root Directory

.
├── ansible/               # Ansible configuration and playbooks
├── terraform/             # Terraform infrastructure definitions
├── scripts/               # Utility scripts for development
├── .env                   # Environment variables
├── README.md              # Project documentation
└── .gitignore             # Git ignore rules

Ansible Structure

ansible/
├── playbooks/             # Deployment playbooks
├── inventory/             # Inventory files for different environments
├── roles/                 # Custom Ansible roles
├── templates/             # Configuration templates
└── ansible.cfg            # Ansible configuration

Terraform Structure

terraform/
├── environments/          # Environment-specific configurations
│   ├── dev/               # Development environment
│   ├── staging/           # Staging environment
│   └── production/        # Production environment
├── modules/               # Reusable Terraform modules
└── shared/                # Shared Terraform configurations

Scripts Directory

scripts/
├── droplet-manager.sh      # Main management script
├── ssh-tunnel.sh          # SSH tunnel management
└── utils/                 # Utility scripts

Environment Files

ansible/group_vars/: Group variables for Ansible
ansible/host_vars/: Host-specific variables for Ansible

Configuration Files

ansible.cfg: Ansible configuration
terraform/shared/provider.tf: Terraform provider configuration
terraform/shared/versions.tf: Terraform version requirements

Configuration

Environment Variables

The only required environment variable is:

To set this up:

  1. Add to Shell Configuration: Add the following to your shell’s rc file (~/.bashrc, ~/.zshrc, etc.):

    export DO_TOKEN="your_digitalocean_api_token"

  2. Reload Shell Configuration:

    source ~/.bashrc  # or ~/.zshrc

Configuration File Setup

The project uses a config.yml file for application and environment-specific settings. To set up your configuration:

  1. Copy the Template:

    cp config.yml.template config.yml

  2. Edit the Configuration: Open config.yml in your text editor and fill in the appropriate values. Refer to the template file for the complete structure and available options.

  3. Save the File: After filling in the values, save the file as config.yml.

Configuration Sections

The configuration file is organized into the following sections:

Notes

Deployment

Local Development

  1. Start Development Environment:

    ./scripts/droplet-manager.sh start

  2. Set Up SSH Tunnel:

    ./scripts/ssh-tunnel.sh start

  3. Deploy Application:

    cd ansible
ansible-playbook -i inventory/dev playbooks/deploy.yml

Staging Environment

  1. Initialize Terraform:

    cd terraform/environments/staging
terraform init

  2. Create Infrastructure:

    terraform apply

  3. Deploy Application:

    cd ../../ansible
ansible-playbook -i inventory/staging playbooks/deploy.yml

Production Environment

  1. Initialize Terraform:

    cd terraform/environments/production
terraform init

  2. Create Infrastructure:

    terraform apply

  3. Deploy Application:

    cd ../../ansible
ansible-playbook -i inventory/production playbooks/deploy.yml

Infrastructure

DigitalOcean Setup

  1. Create Droplet:

    doctl compute droplet create <name> \
  --region nyc3 \
  --image ubuntu-22-04-x64 \
  --size s-1vcpu-1gb \
  --ssh-keys <your-key-fingerprint>

  2. Configure Firewall:

    doctl compute firewall create \
  --name activist-firewall \
  --inbound-rules "protocol:tcp,ports:22,address:0.0.0.0/0" \
  --outbound-rules "protocol:tcp,ports:all,address:0.0.0.0/0"

Network Architecture

Security Considerations

Development

Local Development Setup

  1. Clone the Repository:

    git clone https://github.com/your-username/activist-dev-env.git
cd activist-dev-env

  2. Set Up Environment Variables:

    Create a .env file with your DigitalOcean API token:

    export DO_TOKEN="your_digitalocean_api_token"

  3. Install Dependencies:

    brew install terraform ansible doctl

  4. Initialize Development Environment:

    ./scripts/droplet-manager.sh start

Code Style Guidelines

Testing Guidelines

  1. Shell Scripts:
    • Use bats for unit testing
    • Test error handling and edge cases
    • Verify script output and exit codes
  2. Ansible Playbooks:
    • Use molecule for testing roles
    • Test idempotency
    • Verify playbook execution
  3. Terraform Configurations:
    • Use terraform validate for syntax checking
    • Test plan output
    • Verify infrastructure creation

Contributing Guidelines

  1. Branching:
    • Create feature branches from main
    • Use descriptive branch names
    • Keep branches focused on single features
  2. Pull Requests:
    • Include clear descriptions
    • Reference related issues
    • Ensure all tests pass
  3. Code Review:
    • Review for style and best practices
    • Verify functionality
    • Check for security issues
  4. Documentation:
    • Update README for new features
    • Add inline comments where necessary
    • Document any breaking changes

License

This project is licensed under the MIT License. Below is a summary of the key terms:

Permissions

Conditions

Limitations

Full License Text

The full text of the MIT License is included in the LICENSE file in the root of this repository.

Contributions

By contributing to this project, you agree to license your contributions under the same MIT License terms.

Third-Party Licenses

This project may include third-party libraries or tools, each with its own license. Please refer to the respective documentation for their licensing terms.

Contributing

We welcome contributions from the community! Here’s how you can help improve the Activist Development Environment:

Getting Started

  1. Fork the Repository: Click the “Fork” button on the GitHub repository page to create your own copy.

  2. Clone Your Fork:

    git clone https://github.com/your-username/activist-dev-env.git
cd activist-dev-env

  3. Set Up Development Environment: Follow the Development section to set up your local environment.

Making Changes

  1. Create a Feature Branch:

    git checkout -b feature/your-feature-name
  2. Make Your Changes:
    • Follow the code style guidelines
    • Write tests for new functionality
    • Update documentation as needed

  3. Commit Your Changes:

    Use descriptive commit messages:

    git commit -m "Add feature: your feature description"

  4. Push to Your Fork:

    git push origin feature/your-feature-name

Submitting a Pull Request

  1. Create a Pull Request:
    • Go to the GitHub repository page
    • Click “New Pull Request”
    • Select your feature branch
  2. Describe Your Changes:
    • Provide a clear title and description
    • Reference any related issues
    • Include screenshots or test results if applicable
  3. Address Feedback:
    • Respond to code review comments
    • Make requested changes
    • Push updates to your branch

Code Review Process

Reporting Issues

  1. Check Existing Issues: Search the issue tracker to see if your issue has already been reported.

  2. Create a New Issue:

    • Provide a clear title and description
    • Include steps to reproduce
    • Add relevant logs or screenshots

Code of Conduct

All contributors are expected to follow our Code of Conduct. Please be respectful and considerate in all interactions.

Acknowledgments

We appreciate all contributions, whether it’s code, documentation, or bug reports. Thank you for helping make this project better!

Changelog

[0.1.1] - 2025-02-01

[0.1.0] - 2025-01-31

[0.0.1] - 2025-01-28

Real-time Code Synchronization

This repository includes a real-time code synchronization system that automatically syncs your local code changes to the remote droplet. This ensures that your development environment is always up-to-date with your latest changes.

Overview

The code sync feature is automatically set up and started as part of the droplet-manager.sh --create process. When you create a new droplet, the code sync service will:

  1. Generate a customized sync script based on your configuration
  2. Perform an initial full sync of your project files to the remote droplet
  3. Start watching for file changes and automatically sync them in real-time
  4. Run in the background so you can continue working without interruption

Prerequisites

Managing the Code Sync Service

The code sync service runs automatically, but you can control it manually if needed:

# Stop the code sync service
./code-sync.sh stop

# Start the code sync service in interactive mode
./code-sync.sh interactive

# Start the code sync service in automatic mode
./code-sync.sh

How It Works

The real-time code sync service:

Monitoring and Troubleshooting

To monitor the sync process:

# View sync logs
cat code-sync.log

# Check if the service is running
ps aux | grep code-sync

# Restart the service if needed
./code-sync.sh stop && ./code-sync.sh

Customization

The sync script is generated based on your config.yml settings: