Ξεκινώντας

ΠροαπαιτούμεναΑντιγραφή συνδέσμου ενότητας

• Python 3.13
• uv
• Git

Το Docker είναι προαιρετικό και χρειάζεται μόνο αν θέλετε να χρησιμοποιήσετε την παρεχόμενη τοπική υπηρεσία PostgreSQL.

Εγκατάσταση dependenciesΑντιγραφή συνδέσμου ενότητας

Από το root του repository:

uv sync

Η εντολή διαβάζει τα pyproject.toml και uv.lock, δημιουργεί virtual environment αν χρειάζεται και εγκαθιστά τις pinned dependencies.

Χωρίς database configuration, το project χρησιμοποιεί SQLite. Για PostgreSQL, ακολουθήστε τον οδηγό Database Setup και εγκαταστήστε τον προαιρετικό driver με uv sync --extra postgres.

Έλεγχος ρυθμίσεωνΑντιγραφή συνδέσμου ενότητας

uv run python src/manage.py check

Αναμενόμενο αποτέλεσμα:

System check identified no issues (0 silenced).

Ο έλεγχος επιβεβαιώνει ότι το Django φορτώνει σωστά το project, τα settings, τα apps, τα models και το URL configuration.

Εφαρμογή database migrationsΑντιγραφή συνδέσμου ενότητας

uv run python src/manage.py migrate

Η εντολή δημιουργεί ή ενημερώνει τη βάση που επιλέγει το DATABASE_URL. Αν η μεταβλητή δεν έχει οριστεί, χρησιμοποιείται η προεπιλεγμένη τοπική SQLite database.

Το τοπικό αρχείο database εξαιρείται από το Git:

src/db.sqlite3

First-run setupΑντιγραφή συνδέσμου ενότητας

Αν χρειάζεται να επαναλάβετε συχνά αυτή τη διαδικασία, χρησιμοποιήστε το απομονωμένο onboarding sandbox. Μην διαγράφετε ή κάνετε flush την κανονική development database.

Για νέα εγκατάσταση, δημιουργήστε one-time setup token και προσθέστε το στο .env του server, το οποίο εξαιρείται από το Git, ως BUBLLIO_SETUP_TOKEN. Πρέπει να έχει τουλάχιστον 32 χαρακτήρες. Δημιουργήστε τυχαία τιμή με:

uv run python -c "import secrets; print(secrets.token_urlsafe(32))"

Μετά τις migrations, ξεκινήστε το Django και το React frontend (δείτε το Frontend README) και ανοίξτε το frontend. Η φόρμα setup εμφανίζεται μόνο όταν δεν υπάρχουν Django users ή Organizations, η εγκατάσταση δεν έχει ολοκληρωθεί και έχει ρυθμιστεί server-side setup token.

Συμπληρώστε το token, το username, το email και το password του πρώτου admin, καθώς και το όνομα και το slug του πρώτου workspace. Ο λογαριασμός που δημιουργείται είναι Django superuser και ταυτόχρονα Owner του workspace. Στη συνέχεια συνδεθείτε με αυτόν.

Το SMTP είναι προαιρετικό. Η φόρμα setup έχει τέσσερα βήματα: Admin, Workspace, Email και Review. Μπορείτε να επιστρέψετε σε προηγούμενο βήμα χωρίς να χαθούν οι τιμές, να παραλείψετε το SMTP και να ελέγξετε τα στοιχεία πριν από τη δημιουργία. Για να ρυθμίσετε SMTP κατά το setup, προσθέστε πρώτα το BUBLLIO_EMAIL_ENCRYPTION_KEYS στον server, όπως περιγράφεται στο Email Sending.

Το SMTP password κρυπτογραφείται και αποθηκεύεται στο email account του Organization όταν ολοκληρώσετε το setup. Στο βήμα Email, το Send test email στέλνει πραγματικό μήνυμα στη διεύθυνση που θα δώσετε, χρησιμοποιώντας τις τρέχουσες ρυθμίσεις. Επιτυχής απάντηση API σημαίνει ότι ο SMTP server αποδέχτηκε το μήνυμα· ελέγξτε τα εισερχόμενα για να επιβεβαιώσετε την παράδοση. Το test δεν αποθηκεύει το account και μπορείτε να το παραλείψετε. Τα automation emails δεν δρομολογούνται μέσω αυτού του SMTP account. Μπορείτε να ρυθμίσετε SMTP αργότερα από το authenticated Organization API ή το Django admin.

Το endpoint εφαρμόζει rate limit, ελέγχει το setup token και κλείνει μετά την επιτυχή ολοκλήρωση. Σε μεταγενέστερο maintenance deployment μπορείτε να αφαιρέσετε το BUBLLIO_SETUP_TOKEN ως πρόσθετο μέτρο προστασίας· δεν απαιτείται άμεσο restart. Μην το βάλετε σε μεταβλητές VITE_*, public URL, logs ή version control. Χρησιμοποιήστε HTTPS αν το setup είναι προσβάσιμο μέσω δικτύου. Τα DJANGO_SECRET_KEY, database settings, allowed hosts και οι υπόλοιπες ρυθμίσεις ασφαλείας παραμένουν environment configuration, όχι πεδία της φόρμας browser.

Πρόσκληση μελών της ομάδαςΑντιγραφή συνδέσμου ενότητας

Ανοίξτε ένα workspace και επιλέξτε People. Συμπληρώστε το email του συνεργάτη και επιλέξτε workspace role. Το Bubllio στέλνει invitation μέσω του ενεργού default SMTP account του workspace ή του fallback SMTP της εγκατάστασης. Αν δεν είναι διαθέσιμο κανένα από τα δύο, ρυθμίστε πρώτα SMTP. Το link λήγει σε επτά ημέρες. Νέος χρήστης δημιουργεί account από το link· υπάρχων χρήστης συνδέεται με το email της invitation. Δεν υπάρχει public signup page.

Μετά την αποδοχή, ο χρήστης βλέπει μόνο τα workspaces στα οποία έχει membership. Installation admins μπορούν να δημιουργούν νέα shared workspaces και να ορίζουν το email του business Owner. Αν το email ανήκει σε άλλο άτομο, το workspace παραμένει pending και απρόσιτο μέχρι να αποδεχτεί την invitation. Ο Installation admin μπορεί να ξαναστείλει την invitation ή να ακυρώσει το handoff από τη σελίδα Workspaces.

Installation admins μπορούν να προσκαλέσουν επιπλέον IT admins από τα Account settings. Η invitation χρησιμοποιεί το fallback SMTP της εγκατάστασης, λήγει σε επτά ημέρες και γίνεται αποδεκτή από νέο ή υπάρχον account. Τα δικαιώματα Installation admin δεν προσθέτουν αυτόματα workspace memberships.

Σε deployment, ορίστε το BUBLLIO_APP_URL στο public origin του React app, ώστε τα email links να ανοίγουν τη σωστή εγκατάσταση. Η τοπική προεπιλογή είναι http://127.0.0.1:5173.

Εναλλακτικά: δημιουργία admin από CLIΑντιγραφή συνδέσμου ενότητας

Αν δεν θέλετε να ενεργοποιήσετε τη φόρμα first-run setup, αφήστε το BUBLLIO_SETUP_TOKEN απενεργοποιημένο και δημιουργήστε admin με την εντολή του Django:

uv run python src/manage.py createsuperuser

Χρησιμοποιήστε αυτόν τον λογαριασμό για σύνδεση στο Django admin.

Όλα τα CRM API endpoints απαιτούν authentication. Το REST API χρησιμοποιεί JWT access και refresh tokens. Για browser-based δοκιμές του API, παραμένει διαθέσιμο το Django admin/session login:

http://127.0.0.1:8000/api-auth/login/

Για χρήση με Postman, ζητήστε JWT pair από το POST /api/v1/auth/token/ χρησιμοποιώντας το τοπικό Django username και password. Στείλτε το access token ως Bearer token. Εκτός local development χρησιμοποιήστε HTTPS.

Εκκίνηση serverΑντιγραφή συνδέσμου ενότητας

uv run python src/manage.py runserver

Ανοίξτε:

http://127.0.0.1:8000/admin/
http://127.0.0.1:8000/api-auth/login/
http://127.0.0.1:8000/api/v1/organizations/

Τοπικό emailΑντιγραφή συνδέσμου ενότητας

Από προεπιλογή, τα automation emails εμφανίζονται στο console. Το project χρησιμοποιεί:

EMAIL_BACKEND = "django.core.mail.backends.console.EmailBackend"

Τα μηνύματα εμφανίζονται στο terminal όπου τρέχει το runserver. Τα SMTP accounts του Organization έχουν ξεχωριστό endpoint δοκιμαστικής αποστολής. Η δημιουργία SMTP account δεν αλλάζει τη συμπεριφορά αποστολής email των automations. Για τη διαφορά και το encryption key που απαιτείται για αποθήκευση SMTP password, δείτε το Email Sending.

Δοκιμή automationΑντιγραφή συνδέσμου ενότητας

Ακολουθήστε το πρώτο σας automation για να δημιουργήσετε ενεργό rule, να προσθέσετε Company και να ελέγξετε το email output και το run history. Προς το παρόν, μόνο το company.created εκπέμπεται αυτόματα. Δεν χρειάζεται queue, worker ή workflow server. Ο μελλοντικός visual builder περιγράφεται ξεχωριστά στο Automation Roadmap.

Environment variablesΑντιγραφή συνδέσμου ενότητας

Σε production πρέπει να ορίσετε:

DJANGO_SECRET_KEY

Το local development έχει μη παραγωγική προεπιλογή. Το προαιρετικό DATABASE_URL επιλέγει database· το BUBLLIO_EMAIL_ENCRYPTION_KEYS απαιτείται για αποθήκευση SMTP passwords. Διατηρήστε σταθερό το ενεργό key ring μεταξύ των restarts και ακολουθήστε την τεκμηριωμένη διαδικασία rotation πριν αφαιρέσετε παλιό key. Αν χαθούν όλα τα έγκυρα keys, θα χρειαστεί να καταχωρίσετε ξανά το SMTP password.

Το SMTP account του first-run setup λειτουργεί ως installation fallback για workspaces που δεν έχουν ορίσει δικό τους ενεργό default account. Δείτε επίσης τα Database Setup και Email Sending.