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:

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

Installation using Python​

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

or

Terminal
# installation
./bin/setup-server-env

# activate environment
source ./bin/activate-env
  • Apply database migrations, collect static assets:
info

Karrio uses SQLite by default to simplify the development setup.

If you want to use Postgres instead
  • Change the database config:
...
- DATABASE_ENGINE=sqlite3
- # DATABASE_ENGINE=postgresql_psycopg2
- # DATABASE_USERNAME=postgres
- # DATABASE_PASSWORD=postgres
- # DATABASE_NAME=db
+ # DATABASE_ENGINE=sqlite3
+ DATABASE_ENGINE=postgresql_psycopg2
+ DATABASE_USERNAME=postgres
+ DATABASE_PASSWORD=postgres
+ DATABASE_NAME=db
...

  • Start the database using:
Terminal
docker compose -f docker/docker-compose.yml up -d db
  • Destroy the database using:
Terminal
docker compose -f docker/docker-compose.yml down
Terminal
karrio migrate
karrio collectstatic --noinput
  • Finally, create yourself an admin account:
Terminal
karrio createsuperuser
  • Start the server:
Terminal
./bin/start

Dashboard​

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

Scripts​

Working on Karrio SDK core and all extensions​

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

Working on a single carrier​

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

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

  • Install an extension in dev mode
Terminal
cd karrio
# pip install -e sdk/extensions/[carrier_extension]
pip install -e sdk/extensions/fedex
  • Running tests for a single extension
Terminal
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
Terminal
cd karrio
. ./bin/setup-server-env
  • Running all server tests
Terminal
cd karrio
./bin/run-server-tests
  • Running tests on a single karrio server module
Terminal
cd karrio
# karrio test --failfast karrio.server.[module].tests
karrio test --failfast karrio.server.manager.tests

Reset Karrio database for a fresh reinstall​

Terminal
cd karrio
# stop and remove the database container
docker-compose -f docker/docker-compose.yml down

# start a fresh Postgres container
docker-compose -f docker/docker-compose.yml up -d db

Backup your data​

Terminal
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​

Terminal
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.