> For the complete documentation index, see [llms.txt](https://appseed.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://appseed.gitbook.io/docs/products/django-dashboards/coreui.md).

# Django CoreUI

Django Admin Dashboard generated by the AppSeed platform on top of **CoreUI** design, an iconic free dahsboard template.

> Version: [**v1.0.5**](https://github.com/app-generator/django-coreui/releases) - release date `2022-06-01`

* Built with [CoreUI Generator](https://appseed.us/generator/coreui/)
* UI Kit: `CoreUI`
* SQLite Database, Django Native ORM
* Session-Based Authentication, Forms validation
* Deployment scripts: Docker, Gunicorn/Nginx

## ✨ Environment

To use the starter, [Python3](https://www.python.org) should be installed properly in the workstation. If you are not sure if Python is installed, please open a terminal and type `python --version`. Here is the full list with dependencies and tools required to build the app:

* [Python3](https://www.python.org) - the programming language used to code the app
* [GIT](https://git-scm.com) - used to clone the source code from the Github repository
* Basic development tools (g++ compiler, python development libraries ..etc) used by Python to compile the app dependencies in your environment.
* (Optional) `Docker` - a popular virtualization software

## ✨ Start the app in Docker

> 👉 **Step 1** - Download the code from the GH repository (using `GIT`)

```bash
$ # Get the code
$ git clone https://github.com/app-generator/django-coreui.git
$ cd django-coreui
```

> 👉 **Step 2** - Start the APP in `Docker`

```bash
$ docker-compose up --build 
```

Visit `http://localhost:5085` in your browser. The app should be up & running.

\\

## ✨ Manual Build

> Download the code

```bash
$ # Get the code
$ git clone https://github.com/app-generator/django-coreui.git
$ cd django-coreui
```

\\

### 👉 Set Up for `Unix`, `MacOS`

> Install modules via `VENV`

```bash
$ virtualenv env
$ source env/bin/activate
$ pip3 install -r requirements.txt
```

> Set Up Database

```bash
$ python manage.py makemigrations
$ python manage.py migrate
```

> Start the app

```bash
$ python manage.py runserver
```

At this point, the app runs at `http://127.0.0.1:8000/`.

\\

### 👉 Set Up for `Windows`

> Install modules via `VENV` (windows)

```
$ virtualenv env
$ .\env\Scripts\activate
$ pip3 install -r requirements.txt
```

> Set Up Database

```bash
$ python manage.py makemigrations
$ python manage.py migrate
```

> Start the app

```bash
$ python manage.py runserver
```

At this point, the app runs at `http://127.0.0.1:8000/`.

\\

## ✨ Manage App `Users`

By default, the starter is not provided with users. To access the private pages and the admin section (reserved for `superusers`) follow up the next sections.

### 👉 Create `Superusers`

To access the `admin` section, Django requires `superuser` privilegies. Let's create a new `superuser` and access the `admin` section of the project:

```bash
$ python.exe manage.py createsuperuser
>>> Username (leave blank to use 'test'): test
>>> Email address: admin@appseed.us
>>> Password: *******
>>> Password (again): *******
>>> Superuser created successfully.
```

Once the `superuser` is successfully created, we can access the `admin` section:

`http://localhost:8000/admin/` (make sure you have a `/` at the end).

\\

### 👉 Create (Ordinary) Users

By default, the app redirects guest users to authenticate. In order to access the private pages, follow this set up:

* Start the app via `python manage.py runserver`
* Access the `registration` page and create a new user:
  * `http://127.0.0.1:8000/register/`
* Access the `sign in` page and authenticate
  * `http://127.0.0.1:8000/login/`

\\

## ✨ Codebase structure

The project is coded using a simple and intuitive structure presented below:

```bash
< PROJECT ROOT >
   |
   |-- core/                           # Implements app configuration
   |    |-- settings.py                # Defines Global Settings
   |    |-- wsgi.py                    # Start the app in production
   |    |-- urls.py                    # Define URLs served by all apps/nodes
   |
   |-- apps/
   |    |
   |    |-- home/                      # A simple app that serve HTML files
   |    |    |-- views.py              # Serve HTML pages for authenticated users
   |    |    |-- urls.py               # Define some super simple routes  
   |    |
   |    |-- authentication/            # Handles auth routes (login and register)
   |    |    |-- urls.py               # Define authentication routes  
   |    |    |-- views.py              # Handles login and registration  
   |    |    |-- forms.py              # Define auth forms (login and register) 
   |    |
   |    |-- static/
   |    |    |-- <css, JS, images>     # CSS files, Javascripts files
   |    |
   |    |-- templates/                 # Templates used to render pages
   |         |-- includes/             # HTML chunks and components
   |         |    |-- navigation.html  # Top menu component
   |         |    |-- footer.html      # App Footer
   |         |    |-- scripts.html     # Scripts common to all pages
   |         |
   |         |-- layouts/              # Master pages
   |         |    |-- base.html        # Used by common pages
   |         |
   |         |-- accounts/             # Authentication pages
   |         |    |-- login.html       # Login page
   |         |    |-- register.html    # Register page
   |         |
   |         |-- home/                 # UI Kit Pages
   |              |-- index.html       # Index page
   |              |-- page-404.html    # 404 page
   |              |-- *.html           # All other pages
   |
   |-- requirements.txt                # Development modules - SQLite storage
   |
   |-- .env                            # Inject Configuration via Environment
   |-- manage.py                       # Start the app - Django default start script
   |
   |-- ************************************************************************
```

\\

## ✨ Application Bootstrap Flow

The entry point of the project is the `core.settings.py` file where the project configuration is bundled. The `most important files` that make the project functional are listed below:

* `manage.py` (saved in the root of the project) loads `core/settings.py`
* `core/settings.py`:
  * Loads the `.env` file (dynamic configuration)
  * Loads the project routing:
    * `core.urls.py`
  * Defines the `templates` directory
    * `apps/templates`
  * Defines the `INSTALLED_APPS` section
    * `apps.home` - custom app that serve all pages
  * If the `DB_ENGINE` variable is not present in the environment
    * `SQLite` persistence is used
  * If the `DB_ENGINE` is present
    * The DB URI is built dynamically for `MySql` or `PostgreSQL`.

\\

## ✨ Project Routing

The core file that bundles together all routing rules is `core/urls.py`.

The `home` application being a generic router that serves all pages defined in the `templates/home` directory, should be the last rule defined in the `urlpatterns`.

> NOTE: all new apps, should be included above `apps.home.urls` generic rule.

```python
urlpatterns = [
    path('admin/', admin.site.urls),          # Django admin route
    path("", include("apps.authentication.urls")), # Auth routes - login / register

    # ADD NEW Routes HERE

    # Leave `Home.Urls` as last the last line
    path("", include("apps.home.urls"))
]
```

\\

## ✨ UI Assets and Templates

The project comes with a modern UI fully migrated and usable with Django Template Engine.

### 👉 Page Templates

All pages and components are saved inside the `apps/templates` directory. Here are the standard directories:

* `templates/layouts`: UI masterpages
* `templates/includes`: UI components (used across multiple pages)
* `templates/accounts`: login & registration page
* `templates/home`: all other pages served via a generic routing by `apps/home` app

```bash
< PROJECT ROOT >
   |
   |-- core/                           # Implements app configuration
   |-- apps/
   |    |
   |    |-- home/                      # A simple app that serve HTML files
   |    |-- authentication/            # Handles auth routes (login and register)
   |    |
   |    |-- static/
   |    |    |-- <css, JS, images>     # CSS files, Javascripts files
   |    |
   |    |-- templates/                 # Templates used to render pages
   |         |-- includes/             # HTML chunks and components
   |         |    |-- navigation.html  # Top menu component
   |         |    |-- footer.html      # App Footer
   |         |    |-- scripts.html     # Scripts common to all pages
   |         |
   |         |-- layouts/              # Master pages
   |         |    |-- base.html        # Used by common pages
   |         |
   |         |-- accounts/             # Authentication pages
   |         |    |-- login.html       # Login page
   |         |    |-- register.html    # Register page
   |         |
   |         |-- home/                 # UI Kit Pages
   |              |-- index.html       # Index page
   |              |-- page-404.html    # 404 page
   |              |-- *.html           # All other pages
   |
   |-- ************************************************************************
```

\\

### 👉 Static Assets

The static assets used by the project (`JS`, `CSS`, `images`) are saved inside the `apps/static/assets` folder. This path can be customized with ease via `ASSETS_ROOT` variable saved in the `.env` file.

> How it works

* `.env` defines the `ASSETS_ROOT` variable
* `core/settings.py` read the value of `ASSETS_ROOT` and defaults to `/static/assets` if not found:

```python
# content of core/settings.py (truncated content)

ASSETS_ROOT = os.getenv('ASSETS_ROOT', '/static/assets') 
```

* All pages and components use the `ASSETS_ROOT` variable. Here is a sample extracted from `templates/layouts/base.html`:

```html
<head>

    <!-- Source Code -->
    <link rel="stylesheet" href="{{ ASSETS_ROOT }}/css/style.css">

    <!-- RUNTIME -->
    <link rel="stylesheet" href="/static/assets/css/style.css">
```

At runtime, the `href` property is resolved to `/static/assets/css/style.css` based on the value saved in the `.env` file:

```
# No Slash at the end
ASSETS_ROOT=/static/assets
```

\\

## ✨ Default Apps

The codebase comes with two simple apps that handle the authentication and serve all pages saved in the `apps/templates/home` directory.

### 👉 Authentication App

This default app defined in `apps/authentication` handles the authentication routes `login`, `register`. The most important files that make the authentication usable, are listed below:

* `forms.py` - defines the Login, Registration forms
* `views.py` - implements the login, registration flow
* `routes.py` - map routing rules over the views
* `models.py` - EMPTY file
  * The extended user model is NOT provided

### 👉 Home App

This app returns all pages saved in the `templates/home` directory to authenticated users. In case a page is not found, a generic page is returned using a `404` HTTP error status.

\\

## ✨ Customisation

### 👉 Set up the MySql Database

**Note:** Make sure your Mysql server is properly installed and accessible.

> **Step 1** - Create the MySql Database to be used by the app

* `Create a new MySql` database
* `Create a new user` and assign full privilegies (read/write)

> **Step 2** - Install `mysqlclient` package

```bash
$ pip install mysqlclient
```

> **Step 3** - Edit the `.env` to match your MySql DB credentials. Make sure `DB_ENGINE` is set to `mysql`.

* `DB_ENGINE` : `mysql`
* `DB_NAME` : default value = `appseed_db`
* `DB_HOST` : default value = `localhost`
* `DB_PORT` : default value = `3306`
* `DB_USERNAME`: default value = `appseed_db_usr`
* `DB_PASS` : default value = `pass`

\\

Here is a sample:

```
# .env sample

DB_ENGINE=mysql               # Database Driver
DB_NAME=appseed_flask         # Database Name
DB_USERNAME=appseed_flask_usr # Database User
DB_PASS=STRONG_PASS_HERE      # Password 
DB_HOST=localhost             # Database HOST, default is localhost 
DB_PORT=3306                  # MySql port, default = 3306 
```

At this point, the app should use `MySql` for the persistence layer.

### 👉 Adding a new app

The existing codebase can be extended with ease with new apps and features. Here are the steps that create a new application named `polls`.

> **Create a new app** using `startapp` command (make sure you are in the root of the project)

```bash
$ python manage.py startapp polls
```

> **Write a simple view** for the new app - Edit `polls/views.py`

```python
from django.http import HttpResponse

def index(request):
    return HttpResponse("Hello! This is the polls APP index.")
```

> **Create urls.py** inside the `polls` directory

```python
from django.urls import path

from . import views

urlpatterns = [
    path('', views.index, name='index'),
]
```

> **Update project routing** - `core/urls.py` file:

```python
urlpatterns = [
    path('admin/', admin.site.urls),         
    path("", include("apps.authentication.urls")), 

    # ADD NEW Routes HERE
    path('polls/', include('polls.urls')),  # <-- NEW

    # Leave `Home.Urls` as last the last line
    path("", include("apps.home.urls"))
]
```

> **Enable the new app** - Update `core/settings.py` file:

```python
... (truncated content)

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'polls',                       # <-- NEW
    'apps.home' 
]

... (truncated content)
```

> **Start the project** and access the project in the browser:

`http://localhost:8000/polls/`

![Django new app - browser output.](https://user-images.githubusercontent.com/51070104/172329836-93dfb838-87ba-4067-9983-93a95ca8571c.png)

\\

### 👉 Static Assets for `production`

As explained in the [Static Assets](#static-assets) section, the assets are managed via:

* `apps/static/assets` - the folder where `JS`, `CSS`, and `images` files are saved
* `ASSETS_ROOT` - environment variable, that defaults to `/static/assets` if not defined

In production, the contents of the `apps/static/assets` files should be copied to an external (public) directory and the `ASSETS_ROOT` environment variable updated accordingly.

For instance, if the `static` files are copied to `https://cdn.your-server.com/coreui-assets`, the `.env` file should be updated as below:

```
# No Slash at the end
ASSETS_ROOT=https://cdn.your-server.com/coreui-assets
```

## 🚀 Where to go from here

* 👉 Access the [support](https://appseed.us/support/) page in case something is missing
* 👉 Use [CoreUI Generator](https://appseed.us/generator/coreui/) to generate a new project
* 👉 Check-out the PREMIUM version, [Django Datta Able PRO](https://django-datta-able-pro.appseed-srv1.com/) (`live demo`) for more features and improved UI
  * ✅ `Bootstrap 5` version
  * ✅ More pages & components
  * ✅ `Dark-Mode`
  * ✅ `Dynamic API` feature
  * ✅ Priority on support
  * ✅ [Django Datta Able PRO](https://appseed.us/product/datta-able-pro/django/) - `product page`

![Datta Able PRO - Full-Stack Starter generated by AppSeed.](https://user-images.githubusercontent.com/51070104/170474361-a58da82b-fff9-4a59-81a8-7ab99f478f48.png)