Developing for CCSync
This section gives a brief information about almost everything that you would need to setup CCSync for development, or deployment.
If you still have any queries, contact us on Github
Environment Architecture
The diagram below is a representation of how various components are connected to enable sync 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 docker-prod branch.
- Navigate to production directory by
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" # the url of the web frontend, so as to avoid CORS errors CONTAINER_ORIGIN="http://YOUR_CONTAINER_NAME:8080/" # deployed taskchampion-sync-server container, should be production-syncserver-1 by default
-
Run
docker-compose pull
to pull the CCSync images. - Run
docker-compose up
to finally start the project. - The frontend should now be available on localhost:80, backend on localhost:8000, and syncserver on localhost:8080
Setting up a Development Environment
Prerequisites
-
Docker
-
Google OAuth Keys
Steps to setup the frontend
-
Navigate to the frontend directory and run the command:
npm install
-
Create a
.env
file in the same directory. -
If you want to use docker, set the environment variables in
.env
as:VITE_BACKEND_URL="http://localhost:8000/" # this is the backend to which the app or the web frontend interacts with VITE_FRONTEND_URL="http://localhost:80" # the url of our web frontend, so as to avoid CORS based errors VITE_CONTAINER_ORIGIN="http://localhost:8080/" # url of the deployed taskchampion-sync-server container
-
Else, set the environment variables in
.env
as:VITE_BACKEND_URL="http://localhost:8000/" # this is the backend to which the app or the web frontend interacts with VITE_FRONTEND_URL="http://localhost:5173" # the url of our web frontend, so as to avoid CORS based 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 setup the backend
-
Navigate to the backend directory and run the commands:
go mod download go mod tidy
-
Create a
.env
file in the same directory. -
Go to Google cloud credential page for generating client id and secret.
-
If you want to use docker, set the environment variables in
.env
as: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" # the url of the web frontend, so as to avoid CORS errors CONTAINER_ORIGIN="http://YOUR_CONTAINER_NAME:8080/" # url of the deployed taskchampion-sync-server container
-
Else, set the environment variables in
.env
as: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" # the url of the web frontend, so as 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, run it as a root
user preferably on WSL
or any Linux Distro with a user that has elevated permissions to modify files and directories.
Note: The Taskchampion sync server is currently being pulled from the repository here.
Steps to setup the Taskwarrior Flutter app with CCSync
-
For development/personal purposes, in order to use CCSync with Taskwarrior Flutter app, one needs to setup only the backend and the sync server. The frontend setup is optional.
-
Open the
api_service.dart
file. -
For baseUrl, replace
http://YOUR_IP:8000
with the deployed API endpoint. YOUR_IP refers to the IP address of the terminal or Docker container that is hosting the backend currently. -
For origin, replace
http://localhost:8080
with the deployed sync server endpoint. -
Set
sync.server.origin
in your Taskwarrior configuration to the deployed sync server URL. -
Here's how your api_service.dart should look after these changes:
class ApiService { // Use deployed values for baseUrl and origin String baseUrl = 'http://deployed-api-endpoint.com'; // replace with actual deployed API endpoint String origin = 'http://deployed-sync-server-endpoint.com'; // replace with actual deployed sync server endpoint, although, for now, it is just a placeholder until next release or update // Other ApiService code... }
-
Run the app.
Troubleshooting
The sync might break most of the times due to wrong .env
variables. Please ensure that your docker containers are
visible and accessible, using ping <container_address>
commands.
Testing
- For testing backend, first navigate to the backend directory, and then run the tests
cd backend go test <package_name>
Here, package_name
is the test suite you want to run.
-
Similarly, for testing frontend, first navigate to the frontend directory, and then run the tests
cd frontend npm test
-
Note
: In order to setup / run tests for pages that have any URLs, for example, theHomePage.tsx
, toggle theisTesting
totrue
infrontend/src/components/utils/URLs.ts
Google OAuth Keys
Before starting the frontend, Go to Google cloud credential page for generating client id and secret. Read this guide for more information on these credentials and how these work. Follow these steps:
-
Go to Google's developer console.
-
Create a new project.
-
From within your project, create a new "Client ID" by going to "APIs & Auth" > "Credentials" and clicking on the "Create New Client ID" button.
-
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
-
You will be presented with your newly generated credentials that are required for setting up the backend.