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
On windows, use 0.0.0.0:5002
instead of localhost:5002
Dashboard
Fork karrio-dashboard on Github.
Clone the repository:
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
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.