Skip to main content

Developing Karrio

Documentation for developers contributing to the Karrio code base.

Prerequisites​

Server​

The following steps need to be performed inside a terminal window (Windows user may prefer to use the Windows WSL).

  • Fork karrio on Github.

  • Clone the repository:

git clone https://github.com/[YOUR_USERNAME]/karrio.git
cd karrio

Database​

Setup a PostgreSQL database for the application.

docker-compose up -d db

Installation using Python​

  • Setup a Python environment with all dependencies:
source ./scripts/setup-server-env.sh

or 

# installation
./scripts/setup-server-env.sh

# activate environment
source ./scripts/activate-env.sh
  • Apply database migrations, collect static assets:
karrio migrate
karrio collectstatic --noinput
  • Finally, create yourself an admin account:
karrio createsuperuser
  • Start the server:
karrio runserver 0.0.0.0:5002
caution

On windows, use 0.0.0.0:5002 instead of localhost:5002

Dashboard​

git clone https://github.com/[YOUR_USERNAME]/karrio-dashboard.git
cd karrio-dashboard
  • Install node dependencies:
npm install
  • Setup environment variables:
cp .env.sample .env
caution

On windows set up: NEXT_PUBLIC_KARRIO_API_URL=http://localhost:5002

  • Start the dashboard:
npm run dev

Scripts​

Working on Karrio SDK core and all extensions​

  • Setting up Karrio SDK and all carrier extensions
cd karrio
. ./scripts/setup-sdk-env.sh
  • Running all SDK tests
cd karrio
./scripts/run-sdk-tests.sh

Working on a single carrier​

  • Setup a Python environment with the dev dependencies
cd karrio
./scripts/create-new-env.sh

This will create and activate an isolated Python environment with the dev dependencies required to work on karrio.

  • Install an extension in dev mode
cd karrio
# pip install -e sdk/extensions/[carrier_extension]
pip install -e sdk/extensions/fedex
  • Running tests for a single extension
cd karrio
# python -m unittest discover -v -f sdk/extensions/[carrier_extension]/tests
python -m unittest discover -v -f sdk/extensions/fedex/tests

Working on karrio server​

  • Setting up Karrio server 
cd karrio
. ./scripts/setup-server-env.sh
  • Running all server tests
cd karrio
./scripts/run-server-tests.sh
  • Running tests on a single karrio server module
cd karrio
# karrio test --failfast karrio.server.[module].tests
karrio test --failfast karrio.server.manager.tests

Reset Karrio database for a fresh reinstall​

cd karrio
# stop and remove the database container
docker-compose down

# start a fresh Postgres container 
docker-compose up -d db

Backup your data​

cd karrio
karrio dumpdata -e contenttypes -o [BACKUP_LOCATION_PATH]/data[VERSION].json
# e.g: karrio dumpdata -e contenttypes -o ../backup/data2022.10-3.json

Load dev data​

cd karrio
karrio loaddata [BACKUP_LOCATION_PATH]/data[VERSION].json  
# e.g: karrio loaddata ../backup/data2022.10-1.json

Troubleshooting​

Make sure Docker and Docker Compose work before attempting to run Karrio. We won't be able to assist with your Docker installation.

Make sure you've read the warning about Windows 10 Home. Windows versions before Windows 10 are not officially supported.

If you encounter other problems, see Support.