Developing for CCSync

This section provides a comprehensive guide to setting up CCSync for development or deployment.

If you have any further questions, feel free to contact us on GitHub.

Environment Architecture

The diagram below illustrates how various components are connected to enable synchronization on the CCSync website and the Taskwarrior Flutter App.

Setting Up CCSync for Personal Use

Prerequisites

Docker
Google OAuth Keys

Steps to Run CCSync for Personal Use

Clone the CCSync repository and switch to the docker-prod branch.
Navigate to the production directory using the command: cd production.

Create a file named .backend.env with the following attributes:

CLIENT_ID="client_ID" # Google Auth Secret from Prerequisites
CLIENT_SEC="client_SECRET" # Google Auth Secret from Prerequisites
REDIRECT_URL_DEV="http://localhost:8000/auth/callback" 
SESSION_KEY="generate a secret key using 'openssl rand -hex 32'"
FRONTEND_ORIGIN_DEV="http://localhost" # URL of the web frontend to avoid CORS errors
CONTAINER_ORIGIN="http://YOUR_CONTAINER_NAME:8080/" # Deployed taskchampion-sync-server container, default is production-syncserver-1

Run docker-compose pull to pull the CCSync images.
Run docker-compose up to start the project.
The frontend should now be available at localhost:80, the backend at localhost:8000, and the sync server at localhost:8080.

Setting Up a Development Environment

Prerequisites

Docker
Google OAuth Keys

Steps to Set Up the Frontend

Navigate to the frontend directory and run the following command:
```
npm install
```
Create a .env file in the same directory.

If you want to use Docker, set the environment variables in .env as follows:

VITE_BACKEND_URL="http://localhost:8000/" # Backend URL for app or web frontend interaction
VITE_FRONTEND_URL="http://localhost:80" # Web frontend URL to avoid CORS errors
VITE_CONTAINER_ORIGIN="http://localhost:8080/" # URL of the deployed taskchampion-sync-server container

Otherwise, set the environment variables in .env as follows:

VITE_BACKEND_URL="http://localhost:8000/" # Backend URL for app or web frontend interaction
VITE_FRONTEND_URL="http://localhost:5173" # Web frontend URL to avoid CORS errors
VITE_CONTAINER_ORIGIN="http://localhost:8080/" # URL of the deployed taskchampion-sync-server container

Run the frontend container only:

docker-compose build frontend
docker-compose up

Steps to Set Up the Backend

Navigate to the backend directory and run the following commands:
```
go mod download
go mod tidy
```
Create a .env file in the same directory.
Go to the Google Cloud Credentials page to generate a client ID and secret.

If you want to use Docker, set the environment variables in .env as follows:

CLIENT_ID="client_ID" # Google Auth Secret
CLIENT_SEC="client_SECRET" # Google Auth Secret
REDIRECT_URL_DEV="http://localhost:8000/auth/callback" 
SESSION_KEY="generate a secret key using 'openssl rand -hex 32'"
FRONTEND_ORIGIN_DEV="http://localhost" # Web frontend URL to avoid CORS errors
CONTAINER_ORIGIN="http://YOUR_CONTAINER_NAME:8080/" # URL of the deployed taskchampion-sync-server container

Otherwise, set the environment variables in .env as follows:

CLIENT_ID="client_ID" # Google Auth Secret
CLIENT_SEC="client_SECRET" # Google Auth Secret
REDIRECT_URL_DEV="http://localhost:8000/auth/callback"
SESSION_KEY="generate a secret key using 'openssl rand -hex 32'"
FRONTEND_ORIGIN_DEV="http://localhost:5173" # Web frontend URL to avoid CORS errors
CONTAINER_ORIGIN="http://localhost:8080/" # URL of the deployed taskchampion-sync-server container

Run the backend container only:

docker-compose build backend
docker-compose up

Note: If you plan to run the backend without Docker, it is recommended to run it as a root user, preferably on WSL or any Linux distribution with elevated permissions. This is because the server requires permissions to update your taskrc file based on the logged-in user.

Note: The Taskchampion sync server is currently being pulled from the repository here.

Steps to Set Up the Taskwarrior Flutter App with CCSync

For development or personal use, you only need to set up the backend and the sync server. Setting up the frontend is optional.
Go to Settings -> Turn on Taskchampion Sync.
Navigate back to the menu, click on CCSync Credentials, and paste the credentials from the frontend as specified.
Click Save.
Refresh the tasks. CCSync should now be synced with your Taskwarrior Flutter App.

Troubleshooting

If the sync breaks, it is often due to incorrect .env variables. Ensure that your Docker containers are visible and accessible by using the ping <container_address> command.

Testing

To test the backend, navigate to the backend directory and run:
```
cd backend
go test <package_name>
```

Replace <package_name> with the name of the test suite you want to run.

To test the frontend, navigate to the frontend directory and run:
```
cd frontend
npm test
```

Note: To set up or run tests for pages with URLs (e.g., HomePage.tsx), toggle the isTesting variable to true in frontend/src/components/utils/URLs.ts.

Google OAuth Keys

Before starting the frontend, go to the Google Cloud Credentials page to generate a client ID and secret. Read this guide for more information on these credentials and how they work. These keys are required to generate a consistent Client ID and Encryption Secret for using Taskchampion. If you already have your own keys, you can skip this step.

Steps to Generate Google OAuth Keys:

Go to the Google Developer Console.
Create a new project.
Within your project, create a new "Client ID" by navigating to APIs & Auth > Credentials and clicking on Create New Client ID.
Select Web Application.
Enter the following for Authorized JavaScript Origins:
```
http://127.0.0.1
http://localhost
```
Enter the following for Authorized Redirect URI:
```
http://127.0.0.1:8000/callback/
```
Save your changes.
You will be presented with your newly generated credentials, which are required for setting up the backend.