homebase-calendar-sync

* 1. [Prerequisites](#Prerequisites)
* 2. [Google API Setup](#GoogleAPISetup)
* 3. [Installation](#Installation)
	* 3.1. [Using pip](#Usingpip)
	* 3.2. [From Source](#FromSource)
* 4. [Configuration](#Configuration)
* 5. [Running the Tool](#RunningtheTool)
	* 5.1. [Command Line](#CommandLine)
	* 5.2. [Using Docker](#UsingDocker)

• 1. Docker Deployment Guide
  • 1.1. Prerequisites
  • 1.2. Setting Up the Remote Directory
  • 1.3. Building and Running the Docker Container
  • 1.4. Verifying the Deployment
  • 1.5. Summary
• 1. Setup Guide for Developers
  • 2.1. Prerequisites
  • 2.2. Project Structure
  • 2.3. Setup Script (setup.sh)
    • 2.3.1. Usage
    • 2.3.2. Commands
  • 2.4. Functions
  • 2.5. Running the Tests
  • 2.6. Example Workflow

homebase_calendar_sync --help
usage: homebase_calendar_sync [-h] [--version] [--import-secret [IMPORT_SECRET]] [--reset-remote] [--reset-db] [--reset-events]
                              [--reset-auth] [--reset-local] [--reset-all]

Homebase/Google Calendar Sync CLI

options:
  -h, --help            show this help message and exit
  --version             print package version to console.
  --import-secret [IMPORT_SECRET]
                        Path to 'client_secret.json'
  --reset-remote        Remove all homebase events from Google Calendar for current user and calendar
  --reset-db            reset the events database
  --reset-events        reset both local and remote events
  --reset-auth          reset the authentication cache
  --reset-local         reset local files and configuration
  --reset-all           reset auth config and events database

1. Prerequisites

Before you begin, ensure you have the following installed on your machine:

• Google API Setup
• Python 3.12 or higher
• Docker (optional, for deployment and scheduled runs via CRON)
• Git (optional, for cloning the repository)

2. Google API Setup

1. Create a New Google Developer Project:

   • Go to Google Cloud Console.
   • Create a new project.

2. Activate the Google Calendar API:

   • In the Google Cloud Console, go to the API Library.
   • Search for "Google Calendar API" and enable it for your project.

3. Create an OAuth Consent Screen:

   • In the Google Cloud Console, navigate to "APIs & Services" > "OAuth consent screen".
   • Configure the consent screen for your project, adding necessary details like application name, support email, etc.

4. Create OAuth 2.0 Client IDs:

   • In the Google Cloud Console, go to "APIs & Services" > "Credentials".
   • Create credentials and select "OAuth 2.0 Client IDs".
   • Download the client_secret.json file and save it in your working directory.

3. Installation

3.1. Using pip

pip install homebase_calendar_sync

3.2. From Source

Alternatively, you can install the tool from the source code. Follow these steps:

1. Clone the repository (optional):

   git clone https://github.com/your-username/homebase_calendar_sync.git
   cd homebase_calendar_sync
   

2. Install the dependencies:

   pip install .
   

4. Configuration

Before running the tool, you need to configure it. The configuration file should include your Google API credentials and Homebase login details.

1. Create a configuration file:

   Create a .env file in your working directory with the necessary configurations.

   touch .env

   .env

   CC_HOMEBASE_USERNAME = ""
   CC_HOMEBASE_PASSWORD = ""
   CC_HOMEBASE_EMPLOYEE_FIRSTNAME = ""
   CC_HOMEBASE_EMPLOYEE_LASTNAME = ""
   CC_HOMEBASE_START_DATE = "today"
   CC_HOMEBASE_END_DATE = "today"
   CC_HOMEBASE_DAYS_LOOKAHEAD = "14"
   CC_HOMEBASE_LOOKAHEAD = "True"
   CC_HOMEBASE_TIMEZONE = "America/Chicago"
   

5. Running the Tool

You can run the tool in two ways: directly via command line or using Docker.

5.1. Command Line

1. Run the tool:

   homebase_calendar_sync
   

5.2. Using Docker

• Developers Note: The included Dockerfile and docker-compose.yml are deployment versions and install via pip install homebase. Docker is not used for development, use the venv module instead.

1. Build the Docker image:

   docker build -t homebase_calendar_sync .
   

2. Run the Docker container:

   docker-compose up
   

1. Docker Deployment Guide

This guide provides instructions to deploy the homebase_calendar_sync project using Docker. Ensure you have Docker and Docker Compose installed on your machine.

1.1. Prerequisites

Before you begin, ensure you have the following:

• Docker and Docker Compose installed on your machine.
• Completed the Google OAuth flow on a machine with a web browser.
• .env, .homebase_calendar_sync, and .homebase_calendar_sync_meta files from the Google OAuth setup.

1.2. Setting Up the Remote Directory

1. Create the working directory: Create a directory on your remote machine where you will place the necessary files and run the Docker container.

   mkdir -p ~/homebase_calendar_sync_deployment
   cd ~/homebase_calendar_sync_deployment
   

2. Transfer the necessary files: Copy the .env, .homebase_calendar_sync, and .homebase_calendar_sync_meta files from your local machine (where you completed the Google OAuth flow) to the remote machine's working directory.

   scp /path/to/.env user@remote_machine:~/homebase_calendar_sync_deployment/
   scp /path/to/.homebase_calendar_sync user@remote_machine:~/homebase_calendar_sync_deployment/
   scp /path/to/.homebase_calendar_sync_meta user@remote_machine:~/homebase_calendar_sync_deployment/
   

3. Verify the directory structure: Ensure your working directory on the remote machine contains the necessary files:

   tree ~/homebase_calendar_sync_deployment
   

   The output should look something like this:

   ~/homebase_calendar_sync_deployment
   ├── .env
   ├── .homebase_calendar_sync
   └── .homebase_calendar_sync_meta
   

1.3. Building and Running the Docker Container

1. Create the Dockerfile: Create a Dockerfile in the working directory with the following content:

   FROM python:3.12.3-alpine
   
   ENV PYTHONUNBUFFERED=1
   
   WORKDIR /app
   
   RUN apk add --no-cache gcc musl-dev libffi-dev
   RUN pip install --upgrade pip
   RUN pip install --no-cache-dir homebase_calendar_sync
   
   CMD homebase_calendar_sync
   

2. Create the docker-compose.yml file: Create a docker-compose.yml file in the working directory with the following content:

   version: '3'
   services:
     homebase_calendar_sync:
       build: .
       volumes:
         - .:/app
   

3. Build the Docker image: Navigate to the working directory and build the Docker image.

   docker-compose build
   

4. Run the Docker container: Start the Docker container using Docker Compose.

   docker-compose up
   

1.4. Verifying the Deployment

Once the Docker container is running, you can verify that the homebase_calendar_sync tool is working correctly by checking the logs or running commands inside the container.

1. Check the logs: View the logs of the running container to ensure there are no errors.

   docker-compose logs -f
   

2. Run commands inside the container: Open a shell inside the running container to run additional commands or checks.

   docker-compose exec homebase_calendar_sync sh
   

1.5. Summary

By following these steps, you have set up and deployed the homebase_calendar_sync project using Docker. Ensure your .env, .homebase_calendar_sync, and .homebase_calendar_sync_meta files are correctly placed in the working directory for the tool to function properly. You can now manage and synchronize your Homebase and Google Calendar events seamlessly.

2. Setup Guide for Developers

This guide provides instructions for developers to set up and manage the homebase_calendar_sync project.

2.1. Prerequisites

Ensure you have the following installed on your system:

• Python 3.12+
• pip (Python package installer)
• venv (optional, but recommended for creating isolated Python environments)
• Docker (if using Docker)

2.2. Project Structure

The project structure is as follows:

.
├── Dockerfile
├── README.md
├── docker-compose.yml
├── events.db
├── pyproject.toml
├── setup.sh
└── src
    └── homebase_calendar_sync
        ├── __init__.py
        ├── __main__.py
        ├── config.py
        ├── db
        │   ├── __init__.py
        │   ├── __main__.py
        │   └── models.py
        ├── google_client
        │   ├── __init__.py
        │   ├── __main__.py
        │   ├── auth.py
        │   ├── drive_types.py
        │   └── google_client.py
        └── homebase_calendar_sync.py

2.3. Setup Script (setup.sh)

The setup.sh script is used for setting up the development environment, building the project, and testing deployments. Below are the different commands available in the script.

2.3.1. Usage

Run the script with the appropriate argument to perform the desired action. For example:

./setup.sh dev

2.3.2. Commands

• dev: Set up the development environment.

  ./setup.sh dev
  

• build: Build the project using build and twine.

  ./setup.sh build
  

• pypi: Build the project and upload it to PyPI.

  ./setup.sh pypi
  

• testpypi: Build the project and upload it to TestPyPI.

  ./setup.sh testpypi
  

• testpypi_install: Set up a test environment, install the project from TestPyPI, run tests, and then destroy the environment.

  ./setup.sh testpypi_install
  

• pypi_install: Set up a test environment, install the project from PyPI, run tests, and then destroy the environment.

  ./setup.sh pypi_install
  

• pypi_pre_docker: Prepare the environment for Docker, install the project from PyPI, run tests, and then destroy the environment.

  ./setup.sh pypi_pre_docker
  

2.4. Functions

• dev: Uninstalls homebase_calendar_sync, installs necessary development dependencies, and installs the package in editable mode.
• build: Cleans the build directories, installs necessary build dependencies, and builds the project.
• buildenv: Sets up a virtual environment for testing, copies environment variables, and activates the environment.
• buildenv_pre_docker: Similar to buildenv but moves certain configuration files before setting up the environment.
• destroyenv: Destroys the test environment and reactivates the original environment.
• destroyenv_pre_docker: Moves back configuration files after destroying the test environment.
• homebase_calendar_sync_test: Runs a series of tests on the homebase_calendar_sync package to ensure it is working correctly.

2.5. Running the Tests

The homebase_calendar_sync_test function is designed to test the package installation and functionality. It performs the following tests:

• Checks the help command.
• Runs the main command.
• Tests the --reset-events option.
• Prints the version.

To run these tests, use one of the installation commands (testpypi_install or pypi_install).

2.6. Example Workflow

1. Set up the development environment:

   ./setup.sh dev
   

2. Build the project:

   ./setup.sh build
   

3. Upload to TestPyPI and install for testing:

   ./setup.sh testpypi_install
   

4. Upload to PyPI:

   ./setup.sh pypi
   

5. Prepare the environment for Docker:

   ./setup.sh pypi_pre_docker