From d4a214f2d4affe17546d0214ef8184cb630e5639 Mon Sep 17 00:00:00 2001 From: Ben Haynes Date: Fri, 2 Oct 2020 16:21:20 -0400 Subject: [PATCH] Docs updates --- app/src/modules/docs/components/sections.ts | 76 ++++++-------- docs/concepts/app-overview.md | 98 +++++++++---------- docs/getting-started/contributing.md | 2 +- docs/guides/fields.md | 2 +- docs/guides/installation/docker.md | 18 +++- docs/guides/projects.md | 35 ++++++- ...-variables.md => environment-variables.md} | 0 7 files changed, 126 insertions(+), 105 deletions(-) rename docs/reference/{project-environment-variables.md => environment-variables.md} (100%) diff --git a/app/src/modules/docs/components/sections.ts b/app/src/modules/docs/components/sections.ts index 85e1dc8e12..336bb7e017 100644 --- a/app/src/modules/docs/components/sections.ts +++ b/app/src/modules/docs/components/sections.ts @@ -83,6 +83,34 @@ const sections: Section[] = [ to: '/docs/guides', default: 'readme', children: [ + { + name: 'Projects', + to: '/docs/guides/projects', + }, + { + name: 'Collections', + to: '/docs/guides/collections', + }, + { + name: 'Fields', + to: '/docs/guides/fields', + }, + { + name: 'Users & Roles', + to: '/docs/guides/users-and-roles', + }, + { + name: 'Presets & Bookmarks', + to: '/docs/guides/presets', + }, + { + name: 'Webhooks', + to: '/docs/guides/webhooks', + }, + { + name: 'White-Labeling', + to: '/docs/guides/white-labeling', + }, { name: 'Extensions', to: '/docs/guides/extensions', @@ -125,46 +153,6 @@ const sections: Section[] = [ }, ], }, - { - name: 'Collections', - to: '/docs/guides/collections', - }, - { - name: 'Fields', - to: '/docs/guides/fields', - }, - { - name: 'Presets & Bookmarks', - to: '/docs/guides/managing-presets-and-bookmarks', - }, - { - name: 'Roles & Permissions', - to: '/docs/guides/managing-roles-and-permissions', - }, - { - name: 'Webhooks', - to: '/docs/guides/managing-webhooks', - }, - { - name: 'Creating a Project', - to: '/docs/guides/creating-a-project', - }, - { - name: 'Configuring a Project', - to: '/docs/guides/configuring-the-api', - }, - { - name: 'Setting up a Project', - to: '/docs/guides/configuring-project-settings', - }, - { - name: 'White-Labeling a Project', - to: '/docs/guides/white-labeling-a-project', - }, - { - name: 'Upgrading a Project', - to: '/docs/guides/upgrading-a-project', - }, ], }, { @@ -173,6 +161,10 @@ const sections: Section[] = [ to: '/docs/reference', default: 'readme', children: [ + { + name: 'Environment Variables', + to: '/docs/reference/environment-variables', + }, { name: 'Command Line Interface', to: '/docs/reference/command-line-interface', @@ -181,10 +173,6 @@ const sections: Section[] = [ name: 'Error Codes', to: '/docs/reference/error-codes', }, - { - name: 'Project Env Variables', - to: '/docs/reference/project-environment-variables', - }, ], }, ]; diff --git a/docs/concepts/app-overview.md b/docs/concepts/app-overview.md index c1db7d9afe..6b9f1f8749 100644 --- a/docs/concepts/app-overview.md +++ b/docs/concepts/app-overview.md @@ -79,28 +79,28 @@ A module includes a comprehensive listing of all system users within your projec Similar to other [Item Detail](#) pages, this page provides a custom form for viewing system users. This is also used for editing the "Profile Page" of the current user, which is accessible from the [User Menu](#). Directus ships with a full-featured user system, with the following fields: -* First Name -* Last Name -* Email -* Password -* Avatar -* Location -* Title -* Description -* Tags -* Timezone (User Preference) -* Language (User Preference) -* Theme (User Preference) -* Two-Factor Auth (User Preference) -* Status (Admin Only) -* Role (Admin Only) -* Token (Admin Only) +* **First Name** — The user's given name +* **Last Name** — The user's family name +* **Email** — The user's email address used for login/authenticating and email updates +* **Password** — The private string used for login/authenticating (stored as a secure hash) +* **Avatar** — An image displayed throughout the App that represents the user +* **Location** — Can be used for the user's city, country, office name, etc +* **Title** — The name of the position the user holds at their company or organization +* **Description** — A description or bio of the user +* **Tags** — A set of keywords useful when searching within the User Directory +* **Timezone** — (User Preference) The timezone of the user +* **Language** — (User Preference) The language to use for this user's App locale +* **Theme** — (User Preference) Light, Dark, or Auto (based on the user's OS preferences) +* **Two-Factor Auth** — (User Preference) Enables authenticating with 2FA +* **Status** — (Admin Only) Determines if the user is active within the App/API +* **Role** — (Admin Only) The user's role determines their permissions and access +* **Token** — (Admin Only) A static string used for authenticating within the API The sidebar's info component also includes the following readonly details: -* User Key -* Last Access -* Last Page +* **User Key** — The primary key of the user +* **Last Access** — The timestamp of the user's last App or API action +* **Last Page** — The last App page accessed by the user ::: Extending Users While the fields included out-of-the-box are locked from schema changes, you can extend Directus Users to include additional proprietary fields within [Settings > Data Model](#). @@ -114,23 +114,23 @@ This module aggregates all files within the project into one consolidated librar Similar to other [Item Detail](#) pages, this page provides a custom form for viewing assets and embeds. Directus ships with a full-featured system for digital asset management, with the following fields: -* Title -* Description -* Tags -* Location -* Storage -* Filename Disk -* Filename Download +* **Title** — Pulled from @TODO, falls back to a formatted version of the filename +* **Description** — Pulled from @TODO +* **Tags** — Pulled from @TODO +* **Location** — Pulled from @TODO +* **Storage** — The storage adapter where the asset is saved (readonly) +* **Filename Disk** — The actual name of the file within the storage adapter +* **Filename Download** — The name used when downloading the file via _Content-Disposition_ The sidebar's info component also includes the following readonly details: -* Type -* Dimensions -* Size -* Created -* Owner -* Folder -* [Metadata](#) +* **Type** — The MIME type of the file, displayed in the App as a formatted media type +* **Dimensions** — (Images Only) The width and height of the image in pixels +* **Size** — The file-size the asset takes up within the storage adapter +* **Created** — The timestamp of when the file was uploaded to the project +* **Owner** — The Directus user that uploaded the file to the project +* **Folder** — The current parent folder that contains the file +* **Metadata** — [Metadata](#) @TODO ::: Extending Files While the fields included out-of-the-box are locked from schema changes, you can extend Directus Files to include additional proprietary fields within [Settings > Data Model](#). @@ -140,10 +140,10 @@ While the fields included out-of-the-box are locked from schema changes, you can This module is an internal set of guides, concepts, and reference docs for your project's specific version of Directus. It also includes a dynamic [API Reference](#) that is dynamically tailored to your custom schema. The docs are organized into four distinct sections: -* [Getting Started](#) — Novice Oriented. For a platform intro and installation. -* [Concepts](#) — Learning Oriented. For understanding the platfom. -* [Guides](#) — Problem Oriented. Follow along with steps while working. -* [Reference](#) — Information Oriented. Look up info and specs while working. +* [Getting Started](#)** — Novice Oriented. For a platform intro and installation. +* [Concepts](#)** — Learning Oriented. For understanding the platfom. +* [Guides](#)** — Problem Oriented. Follow along with steps while working. +* [Reference](#)** — Information Oriented. Look up info and specs while working. ::: Updating the Docs Our docs are written in markdown (with some additional VuePress styling like this hint box), and available for editing/fixing via [GitHub](*). @@ -157,20 +157,20 @@ This module provides a collective timeline of all actions taken within the proje Unlike other item detail pages, activity items are **readonly** (for proper accountability) and open in a modal window with the following fields: -* User -* Action -* Date -* IP Address -* User Agent -* Collection -* Item +* **User** — The Directus user that performed the action +* **Action** — The specific action taken, eg: Create, Update, Delete, Authenticate, etc +* **Date** — The timestamp of when the action was performed +* **IP Address** — The IP address of the device from which the action was performed +* **User Agent** — The description of the browser that was used to perform the action +* **Collection** — The collection affected by the action +* **Item** — The item (within the above Collection) affected by the action # Settings This module is only available to users within [admin roles](#). This is where your project is configured, and the first place to go after installation. It includes the following sections: -* Project Settings -* Data Model -* Roles & Permissions -* Presets & Bookmarks -* Webhooks +* [Project Settings](#) +* [Data Model](#) +* [Roles & Permissions](#) +* [Presets & Bookmarks](#) +* [Webhooks](#) diff --git a/docs/getting-started/contributing.md b/docs/getting-started/contributing.md index a80f7cbeda..6ba8d91be3 100644 --- a/docs/getting-started/contributing.md +++ b/docs/getting-started/contributing.md @@ -84,7 +84,7 @@ npm install npm run dev ``` -### 7. Make your fixes/changes +### 6. Make your fixes/changes At this point you are ready to start working on Directus! Before diving in however, it's worth reading through our docs on [submitting a pull-request](#Submitting-a-Pull-Request). diff --git a/docs/guides/fields.md b/docs/guides/fields.md index 891b42da17..743cd2f669 100644 --- a/docs/guides/fields.md +++ b/docs/guides/fields.md @@ -1,6 +1,6 @@ # Fields -> TK +> You can manage your fields within the Data Model section of the App's Settings, via the [API Fields Endpoint](#), or directly within the database. If you're unfamiliar with Directus Fields, please start by reading our [Understanding Fields](#) docs. ## Creating a Field diff --git a/docs/guides/installation/docker.md b/docs/guides/installation/docker.md index 5f254be1f4..9c30865e2d 100644 --- a/docs/guides/installation/docker.md +++ b/docs/guides/installation/docker.md @@ -1,11 +1,19 @@ # Installing with Docker -## 1. TK +```bash +docker run -p 8055:8055 directus/directus +``` -## 2. TK - -## 3. TK +## Installing Specific Versions ```bash -docker-compose up -d +docker run -p 8055:8055 directus/directus:v9 +docker run -p 8055:8055 directus/directus:v9.1 +docker run -p 8055:8055 directus/directus:v9.1.2 +``` + +## Setting Environment Variables + +```bash +docker run -e ENV_VAR=VALUE -p 8055:8055 directus/directus ``` diff --git a/docs/guides/projects.md b/docs/guides/projects.md index 3c5ec3c23f..5fbda6e7db 100644 --- a/docs/guides/projects.md +++ b/docs/guides/projects.md @@ -1,21 +1,46 @@ # Projects -> TK +> Every installation of Directus creates a single project. If you're unfamiliar with Directus Projects, please start by reading our [Platform Overview](#). ## Creating a Project -### npm +To install Directus, choose one of the following methods. -### Docker +* [Command Line Interface (CLI)](/guides/installation/cli.md) +* [Docker](/guides/installation/docker.md) +* [Manually](/guides/installation/manual.md) -### DigitalOcean One-Click +### Deployment Guides -### Manual Installation +* [Amazon AWS](#) +* [DigitalOcean Droplet](#) +* [DigitalOcean One-Click](/guides/installation/digitalocean-one-click.md) +* [Google App Engine](#) +* [Heroku](/guides/installation/heroku.md) +* [Microsoft Azure](#) ## Configuring a Project +All project configuration is handled by the `.env` file within the `/api` directory. This file accepts a number of environment variables, each is explained in the following reference: + +* [Environment Variables](#) + ## Upgrading a Project +@TODO + ## Backing-up a Project +1. Make a copy of the **files within each storage adapter**, and store them in a safe place +2. Make a copy of the **Env file** (`/api/.env`), and store it in a safe place +3. Run the **Backup API Endpoint** (`/backup`) to create a SQL dump of your database + ## Deleting a Project + +1. Optional: Backup any local files stored within the project's root directory +2. Optional: Backup any custom code or extensions within the project's root directory +3. Optional: Backup your entire database, only system tables, or only project tables +4. Delete the project's root directory from the server +5. Delete all Directus system tables (`directus_*`) from the database + +After completing this process, you will be left with a pure SQL database, with no trace that Directus was ever installed. Any external services connecting to your database's project tables directly (eg: pure SQL queries) should continue working normally. diff --git a/docs/reference/project-environment-variables.md b/docs/reference/environment-variables.md similarity index 100% rename from docs/reference/project-environment-variables.md rename to docs/reference/environment-variables.md