From c0964195ad0eb2ed5fe198fb1b4e6621854e484e Mon Sep 17 00:00:00 2001 From: Marc Aymerich Date: Tue, 16 Feb 2016 11:14:38 +0000 Subject: [PATCH] Updated README --- README.md | 41 +++++++++++--- docs/README.md | 115 ---------------------------------------- docs/create-services.md | 94 ++++++++++++++++++++++++++++++++ 3 files changed, 127 insertions(+), 123 deletions(-) create mode 100644 docs/create-services.md diff --git a/README.md b/README.md index b5530573..0cc307da 100644 --- a/README.md +++ b/README.md @@ -13,21 +13,23 @@ Motivation ---------- There are a lot of widely used open source hosting control panels, however, none of them seems apropiate when you already have an existing service infrastructure or simply you want your services to run on a particular architecture. -The goal of this project is to provide the tools for easily build a fully featured control panel that is not tied to any particular service architecture. - +The goal of this project is to provide the tools for easily build a fully featured control panel that is not tied to any particular service architecture. Orchestra Overview -------- -Django-orchestra is mostly a bunch of [plugable applications](orchestra/apps) providing common functionalities, like service management, resource monitoring or billing. +* The **admin interface** is based on [Django Admin](https://docs.djangoproject.com/en/dev/ref/contrib/admin/). The resulting interface is very model-centric with a limited workflow pattern: change lists, add and change forms. The advantage is that only little declarative code is required. +* It does **not** provide a **customer-facing interface**, but provides a REST API that allows you to build one. +* Service [orchestration](orchestra/contrib/orchestration), [resource management](orchestra/contrib/resources), [billing](orchestra/contrib/bills), [accountancy](orchestra/contrib/orders) is provided in a decoupled way, meaning: + * You can [develop new services](docs/create-services.md) without worring about those parts + * You can replace any of these parts by your own implementation without carring about others + * You can reuse any of those modules on your Django projects +* Be advised, because its flexibility Orchestra may be more difficult to deploy than traditional web hosting control panels. -The admin interface relies on [Django Admin](https://docs.djangoproject.com/en/dev/ref/contrib/admin/), but enhaced with [Django Admin Tools](https://bitbucket.org/izi/django-admin-tools) and [Django Fluent Dashboard](https://github.com/edoburu/django-fluent-dashboard). [Django REST Framework](http://www.django-rest-framework.org/) is used for the REST API, with it you can build your client-side custom user interface. - -Every app is [reusable](https://docs.djangoproject.com/en/dev/intro/reusable-apps/), this means that you can add any Orchestra application into your Django project `INSTALLED_APPS` strigh away. -However, Orchestra also provides glue, tools and patterns that you may find very convinient to use. Checkout the [documentation](http://django-orchestra.readthedocs.org/) if you want to know more. ![](docs/images/index-screenshot.png) + Fast Deployment Setup --------------------- This deployment is not suitable for production but more than enough for checking out this project. @@ -52,10 +54,33 @@ python3 panel/manage.py runserver Now you can see the web interface on http://localhost:8000/admin/ - Checkout the steps for other deployments: [development](INSTALLDEV.md), [production](INSTALL.md) +Quick start +----------- +0. Install django-orchestra following any of these methods: + 1. [PIP-only, Fast deployment setup (demo)](#fast-deployment-setup) + 2. [Docker container (development)](INSTALLDEV.md) + 3. [Install on current system (production)](INSTALL.md) + +1. Copy orchestra SSH key to the servers to be managed, you can use `ssh-copy-id`: + ```bash + orchestra@panel:~ ssh-copy-id root@server.address + ``` + Then add the servers using the web interface `/admin/orchestration/servers`, check that the SSH connection is working and Orchestra can report the uptime of the servers. + +2. Now configure service by service (domains, databases, webapps, websites, ...): + 1. Add the route via `/admin/orchestration/route/` + 2. Configure related settings on `/admin/settings/setting/` + 3. If required, configure related resources like Account disc limit, VPS traffic, etc `/resources/resource/` + 3. Test that everything works as expected by creating and deleting service instances + 4. Do the same for the other services + +3. Configure billing by adding services `/admin/services/service/add/` and plans `/admin/plans/plan/`. Once a service is created hit the *Update orders* button to create the orders for the existing service instances. + + + License ------- Copyright (c) 2014 - Marc Aymerich and individual contributors. diff --git a/docs/README.md b/docs/README.md index dff31548..b055f522 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,125 +1,10 @@ # Documentation -### Quick start -0. Install django-orchestra following any of these methods: - 1. [PIP-only, Fast deployment setup (demo)](README.md#fast-deployment-setup) - 2. [Docker container (development)](INSTALLDEV.md) - 3. [Install on current system (production)](INSTALL.md) - -1. Copy orchestra SSH key to the servers to be managed, you can use `ssh-copy-id`: - ```bash - orchestra@panel:~ ssh-copy-id root@server.address - ``` - Then add the servers using the web interface `/admin/orchestration/servers`, check that the SSH connection is working and Orchestra can report the uptime of the servers. - -2. Now configure service by service (domains, databases, webapps, websites, ...): - 1. Add the route via `/admin/orchestration/route/` - 2. Configure related settings on `/admin/settings/setting/` - 3. If required, configure related resources like Account disc limit, VPS traffic, etc `/resources/resource/` - 3. Test that everything works as expected by creating and deleting service instances - 4. Do the same for the other services - -3. Configure billing by adding services `/admin/services/service/add/` and plans `/admin/plans/plan/`. Once a service is created hit the *Update orders* button to create the orders for the existing service instances. - - ### Architecture * [Orchestration](../orchestra/contrib/orchestration) * [Orders](../orchestra/contrib/orders) * [Resources](../orchestra/contrib/resources) -### Creating New Services - -1. Think about if the service can fit into one of the existing service models like: SaaS or WebApps, refere to the related documentation if that is the case. -2. Create a new django app using `startapp` management command. For ilustrational purposes we will create a crontab services that will allow orchestra to manage user-based crontabs. - ```bash - python3 manage.py startapp crontabs - ``` -3. Add the new *crontabs* app to the `INSTALLED_APPS` in your project's `settings.py` -3. Create a `models.py` file with the data your service needs to keep in order to be managed by orchestra - ```python - from django.db import models - - class CrontabSchedule(models.Model): - account = models.ForeignKey('accounts.Account', verbose_name=_("account")) - minute = models.CharField(_("minute"), max_length=64, default='*') - hour = models.CharField(_("hour"), max_length=64, default='*') - day_of_week = models.CharField(_("day of week"), max_length=64, default='*') - day_of_month = models.CharField(_("day of month"), max_length=64, default='*') - month_of_year = models.CharField(_("month of year"), max_length=64, default='*') - - class Meta: - ordering = ('month_of_year', 'day_of_month', 'day_of_week', 'hour', 'minute') - - def __str__(self): - rfield = lambda f: f and str(f).replace(' ', '') or '*' - return "{0} {1} {2} {3} {4} (m/h/d/dM/MY)".format( - rfield(self.minute), rfield(self.hour), rfield(self.day_of_week), - rfield(self.day_of_month), rfield(self.month_of_year), - ) - - class Crontab(models.Model): - account = models.ForeignKey('accounts.Account', verbose_name=_("account")) - schedule = models.ForeignKey(CrontabSchedule, verbose_name=_("schedule")) - description = models.CharField(_("description"), max_length=256, blank=True) - command = models.TextField(_("content")) - - def __str__(self): - return (self.description or self.command)[:32] - ``` - -4. Create a `admin.py` to enable the admin interface, refere to [Django Admin documentation](https://docs.djangoproject.com/en/1.9/ref/contrib/admin/) for further customization. - ```python - from django.contrib import admin - from .models import CrontabSchedule, Crontab - - class CrontabScheduleAdmin(admin.ModelAdmin): - pass - - class CrontabAdmin(admin.ModelAdmin): - pass - - admin.site.register(CrontabSchedule, CrontabScheduleAdmin) - admin.site.register(Crontab, CrontabAdmin) - ``` - -5. Create a `api.py` to enable the REST API. - -6. Create a `backends.py` fiel with the needed backends for service orchestration and monitoring. - ```python - import os - import textwrap - from django.utils.translation import ugettext_lazy as _ - from orchestra.contrib.orchestration import ServiceController, replace - from orchestra.contrib.resources import ServiceMonitor - - class UNIXCronBackend(ServiceController): - """ - Basic UNIX cron support. - """ - verbose_name = _("UNIX cron") - model = 'crons.CronTab' - - def prepare(self): - super(UNIXCronBackend, self).prepare() - self.accounts = set() - - def save(self, crontab): - self.accounts.add(crontab.account) - - def delete(self, crontab): - self.accounts.add(crontab.account) - - def commit(self): - for account in self.accounts: - crontab = None - self.append("echo '' > %(crontab_path)s" % context) - for crontab in account.crontabs.all(): - self.append(" - ``` -7. Configure the routing - - - diff --git a/docs/create-services.md b/docs/create-services.md new file mode 100644 index 00000000..d0224237 --- /dev/null +++ b/docs/create-services.md @@ -0,0 +1,94 @@ +# Creating New Services + +1. Think about if the service can fit into one of the existing service models like: SaaS or WebApps, refere to the related documentation if that is the case. +2. Create a new django app using `startapp` management command. For ilustrational purposes we will create a crontab services that will allow orchestra to manage user-based crontabs. + ```bash + python3 manage.py startapp crontabs + ``` +3. Add the new *crontabs* app to the `INSTALLED_APPS` in your project's `settings.py` +3. Create a `models.py` file with the data your service needs to keep in order to be managed by orchestra + ```python + from django.db import models + + class CrontabSchedule(models.Model): + account = models.ForeignKey('accounts.Account', verbose_name=_("account")) + minute = models.CharField(_("minute"), max_length=64, default='*') + hour = models.CharField(_("hour"), max_length=64, default='*') + day_of_week = models.CharField(_("day of week"), max_length=64, default='*') + day_of_month = models.CharField(_("day of month"), max_length=64, default='*') + month_of_year = models.CharField(_("month of year"), max_length=64, default='*') + + class Meta: + ordering = ('month_of_year', 'day_of_month', 'day_of_week', 'hour', 'minute') + + def __str__(self): + rfield = lambda f: f and str(f).replace(' ', '') or '*' + return "{0} {1} {2} {3} {4} (m/h/d/dM/MY)".format( + rfield(self.minute), rfield(self.hour), rfield(self.day_of_week), + rfield(self.day_of_month), rfield(self.month_of_year), + ) + + class Crontab(models.Model): + account = models.ForeignKey('accounts.Account', verbose_name=_("account")) + schedule = models.ForeignKey(CrontabSchedule, verbose_name=_("schedule")) + description = models.CharField(_("description"), max_length=256, blank=True) + command = models.TextField(_("content")) + + def __str__(self): + return (self.description or self.command)[:32] + ``` + +4. Create a `admin.py` to enable the admin interface, refere to [Django Admin documentation](https://docs.djangoproject.com/en/1.9/ref/contrib/admin/) for further customization. + ```python + from django.contrib import admin + from .models import CrontabSchedule, Crontab + + class CrontabScheduleAdmin(admin.ModelAdmin): + pass + + class CrontabAdmin(admin.ModelAdmin): + pass + + admin.site.register(CrontabSchedule, CrontabScheduleAdmin) + admin.site.register(Crontab, CrontabAdmin) + ``` + +5. Create a `api.py` to enable the REST API. + +6. Create a `backends.py` fiel with the needed backends for service orchestration and monitoring. + ```python + import os + import textwrap + from django.utils.translation import ugettext_lazy as _ + from orchestra.contrib.orchestration import ServiceController, replace + from orchestra.contrib.resources import ServiceMonitor + + class UNIXCronBackend(ServiceController): + """ + Basic UNIX cron support. + """ + verbose_name = _("UNIX cron") + model = 'crons.CronTab' + + def prepare(self): + super(UNIXCronBackend, self).prepare() + self.accounts = set() + + def save(self, crontab): + self.accounts.add(crontab.account) + + def delete(self, crontab): + self.accounts.add(crontab.account) + + def commit(self): + for account in self.accounts: + crontab = None + self.append("echo '' > %(crontab_path)s" % context) + for crontab in account.crontabs.all(): + self.append(" + ``` +7. Configure the routing + + + +