Support and FAQ on one crazy-long page.
Frequently asked questions.
- Why can't I upload files?
- This is probably due to your media folder permissions. Ensure that all media folders have write access and that your php.ini file has the correct values for uploads and timeouts.
- What are some of the ways to manage data within Directus?
- There are quite a few! A couple for media, some for text, a few for relational data, checkboxes, tags and too many more to name here. A complete list of input styles can be found here.
- Can I drag and drop files into Directus?
- Yes. If you have a modern browser supporting drag and drop you can drop one or multiple files from your computer directly into any input that accepts media.
- Can Directus handle a lot of media?
- Sure. By lazy-loading optimized images, creating all your thumbnails on the fly, auto-choosing date ranges and more, Directus can manage loads of media items. And since you can choose from existing items, you'll never upload a file twice.
- Is Directus really that easy to setup?
- Definitely. After running the three step installer, just add tables, fields and datatypes to your database as usual. Directus is based on your structure... so you don't need to set it up at all.
- What embed video sites is Directus compatible with?
- Currently Vimeo and Youtube. Directus grabs the title, description, length and even a thumbnail of any videos you add. And adding videos is as easy as pasting in the URL.
This step by step guide walks you through the entire process of getting Directus up and running on your web server. This is an easy process that can be done by anyone with access to create a database on your web server and a basic understanding of FTP. If you run into any trouble along the way try our troubleshooting section for further help.
1. Check requirements
Before downloading, you should ensure that your server meets the minimum requirements to run the current version of Directus. Below are the requirements for the core of Directus, all of which are typically the default settings:
- PHP 5.2
- MySQL 4
- PDO with MySQL Extension - For security
- Register Globals Off - For security
- Safe Mode Off - For security
- GD Library - Used to alter media (such as auto-thumbnail creation)
- File Uploads Enabled - For adding media from your computer
- cURL Enabled - For adding media from other sites (such as YouTube or Vimeo)
Note: There may be additional requirements for any plugins you use.
2. Download the latest version of Directus
Click the download button at the top of this site to get a copy of the current version of Directus. All downloads are available as a zip or tar file.
3. Upload the files to your server
If you are using the zip file you’ll need to unzip the file on your personal computer and then use your favorite FTP client to upload the “directus” folder to the web server directory in which you would like Directus to reside (typically alongside your website files in the html root directory).
If you are using the tar file you’ll simply upload the file to your web server directory in which you would like Directus to reside (typically alongside your website files in the html root directory). You’ll then need to untar the file.
Note: You may rename the “directus” folder to another name at this point to help keep its location a secret from malicious wrong-doers.
4. Install Directus
Once the files are on your web server you should run the installation by navigating to the install page using your favorite web browser. The install file can be found within the “directus” (or whatever it was renamed) folder you just uploaded in step 3.
The URL will typically look something like http://your-website.com/directus/install.php
Agreement: Before Directus is installed you will have to read and agree to the license
Check: Directus will now run a check to ensure your server has the correct settings. If there are any issues Directus will let you know so you may correct them, otherwise installation will automatically continue.
Database: If you do not have a database for this website on your web server already you’ll want to create one along with a MySQL user that has all privileges to access and modify it. Enter this database info within the install fields:
- Database Host: Typically localhost, but may vary depending on your web host
- Database Name This is the name of the database you’ll use for this site
- Username: Your MySQL username with privileges to the above database.
- Password: Your MySQL password to the above username.
- Table Prefix: If you want to limit the tables visible within this install of Directus enter a prefix here such as “website_”. Note: You cannot use “directus_” as that is reserved for directus system tables.
- Demo Table: Checking this will add a table within your database/Directus containing core fields and a few basic fields.
Settings: If Directus was able to connect to the database with the info provided you will be prompted for some information about the site:
- Site Name: Displayed at the top of the CMS, for example: My Company
- Site URL: To link to your site from Directus, for example: http://my-company.com
- First/Last Name: The name for your first administrator within Directus. You can always change this, or add more admin users later.
- Email: The email address for the first admin user, this will be used when logging in, if you forget your password or if you’d like to have your Directus messages to forward to your email.
- Password/Confirm: A password for the first admin user.
- At least 7 characters
- Allows letters, numbers and _@!#$%^&*
You will now be redirected to the login page where you’ll enter the email and password you saved above. The first time you log in, Directus will attempt to delete the install.php file to ensure no one else can change your settings. If Directus is unable to remove the install.php file it will give you an alert reminding you to remove it manually.
Now that you have Directus up and running on your web server it’s time to configure it to format your data, add any other users that need access and finally set the privileges for those users.
The settings page (only available to admin users) allows you to set all the options specific to the website/database you are managing. In the left column you will find the Directus global settings, while in the right column you can change database settings for each table and field.
Here is a description of the fields in the top of the left column:
- Site Name: Displayed at the top of the CMS, for example: My Example
- Site URL: To link to your site from Directus, for example: http://my-example.com
- CMS Color: We provide you with a number of color options to help match Directus to your company or organization’s identity.
- Green (Default)
- CMS Users Auto Logout: This is an amount of time in minutes before an inactive (on the same page) Directus user will be automatically logged out. By default this is set to 43200 minutes (or 30 days) but you can choose any number, or zero (0) to turn this feature off. If a user is on the same page for the set amount of minutes Directus will ask if they are still there giving them one minute to answer before logging them out without saving. Setting this feature too low may result in users editing time-consuming items to be asked too often if they are still there.
Next in the left column are the media settings:
- Media Folder: This is the path to where you would like Directus to store any uploaded media items and is relative to your site (alongside your directus folder, not in it). By default this is set to “media/files/”:
/html /site-files.php /directus/ /all-the-directus-files-are-in-here /media/ /files/ /media-will-be-uploaded-here
- Unique: Uses a random string of 32 characters as the file name which can be useful to help keep information regarding media private but also abandons any clear way of discerning files.
- Example: 92a39adf91b3d83bdf6761eeed75d37a.jpg
- Sequential: Stores files by their database ID padded to six digits with zeros.
- Examples: 000001.jpg, 000036.jpg, 002193.jpg
- Original Filename: Keeps the original name of the file from when it was uploaded (replacing spaces with dashes). If a file with that name already exists then Directus will append a dash and a sequential number to the filename.
- Examples: original-name.jpg, original-name-1.jpg, original-name-2.jpg
- Width: This is the desired width of the thumbnail
- Height: This is the desired height of the thumbnail
- Crop: If checked, the thumbnail will be exactly the dimensions set above, shrinking the image to as close as possible and then trimming the excess. If unchecked, the image will be fit within the boundaries set above leaving the aspect ratio the same.
Note: You can add more allowed auto-thumbnails at any point, however removing one from the list will only stop new auto-thumbnails from being created... not delete existing thumbnails.
Next in the left column is the View Server Details button. Clicking on this will show you useful information about this instance of Directus such as:
- The path to the Directus folder
- MySQL user and database information
- PHP information including the status of required PHP settings and extensions
- Permissions for folders Directus needs writable access to (755)
Note: Clicking Show Extended Details will give you all current session variables for your user as well as a printout of the php_info() function from your server.
In the right column are the settings for individual tables and fields available to Directus. Clicking the table names will cause it to expand, revealing options for that table and the fields therein.
- Hidden: If checked, this table will be hidden within Directus (except on the settings page)
Single: If checked, this table will only ever contain a single item. If clicked from the tables page, the user will be taken directly to the edit page, bypassing the intermediate browse page. An example of when to use this would be for an "about" page which you would presumably only have one of. Single tables have an arrow () on top of the normal table icon reminding the user of this setting.
Normal Table: Tables => Browse Items => Edit Item
Single Table: Tables => Edit Item
Within each table is a list of the fields it contains. Although default values may suffice in some situations, each field has several properties allowing you to further adjust to your site’s needs. There are:
- Options: This is possibly the most significant feature within Directus. Based on the field’s datatype [link to explanation of datatype] Directus allows a number of different options for how users will view, add and manipulate data. The available options are shown within a dropdown with the most common option selected by default. Some field options might offer (or even require) further setup to function properly, these will show a “more options” link when selected from the dropdown. This being such an expansive feature we have a separate area for its documentation.
- Required: If checked, this field will be required when saving from the add or edit page. Required fields are annotated by an asterisk* beside the field name on the edit page. It is worth pointing out that some field types don’t enforce the required feature such as checkboxes.
- Hidden: If checked, this field will be hidden within this table in Directus.
- Primary: Every table needs one field that acts as a title for items when displayed within Directus. For example, when making an edit of an item, the primary field is used on the dashboard to show which item was edited. By default the first field is always chosen.
- Note: Directus uses the field names themselves to let users know what they are editing, but sometimes more information can be useful. This note is displayed in light-gray beside the field name on the edit/add page. Limited to 255 characters.
When installing Directus you are prompted to enter the information for your first admin user. After you have updated all the Directus settings above you’ll want to start adding more users. Here are the major differences between the three different types of users:Admin Users:
- Can see the settings tab as well as view and change Directus settings
- Can add new users
- Can edit all users, and:
- Can change usernames
- Can make users into admin users
- Can set user abilities such as change media or send messages
- Can make a user inactive
- Can see and edit the privileges matrix on the user settings page
- Can see all logged errors within the dashboard
- Also have all the privileges of a normal user
- Can not see the settings tab or make any changes therein
- Can see basic user info via the users page
- Can edit only their own user settings
- Are restricted by their privileges matrix set by the admins
- Can not log in or access Directus in any way
- Do not have messages forwarded to their email
- Appear grayed out and at the bottom of the users list
Note: Be careful not to make yourself inactive as you will be logged out and denied further access immediately upon saving. If you try to do this Directus will warn but not stop you.
In addition to the normal left column of fields on the user settings page, admins alone see a privileges matrix on the right side of the page. This matrix has a row for each table within Directus as well as columns of privileges, allowing admins to limit access very specifically.
Note: Clicking on a table name will toggle all privileges for that table. Clicking a column header will toggle that privilege for all tables (except view, which toggles all privileges since if you can’t see it you can’t do much else). And clicking the top left cell labeled “table” toggles all privileges for all tables.
This section describes how you (the normal user or client) will interact with Directus as a Content Management System (CMS) to a website or more simply, as a Database Administration Tool for MySQL.
At the top of every Directus page is a header and a group of tabs to easily navigate around the CMS. Below is a description of these elements:
Header: Visible on all pages even when scrolling, the header contains the following (left to right):
- Site Name: This is where the name of the managed site or project is displayed. It can be changed on the settings page by admin users.
- View Site: This provides easy access to your managed site in a new window. It can be changed on the settings page by admin users.
- Activity Throbber: This little guy will let you know when Directus is currently processing something. Normally hidden, you will see this indicator on page loads, once a minute to verify security, and whenever you perform an action that doesn’t have an activity alert.
- Avatar: This is the image associated with the user currently logged in. It can be changed on the user settings page.
- User’s Name: Shown in white, this is the name of the user currently logged in. Hovering over this username will display a list of users currently online.
- Inbox: This is the link to your Directus messages. The number of unread messages will also be shown if there are any.
- User Settings: This is a shortcut to the currently logged in user’s settings page.
- Logout: Clicking this link will log you out of Directus and deletes all cookies (except a cookie that stores your last page for next time you log in) and redirects you to the login page.
Tabs: Depending on your setup of Directus and user type you will see different tabs in this area. Each links to a page described later in the help docs:
- Dashboard: Links to the dashboard page.
- Tables: Takes you to the tables page which is the default page within Directus. The badge on this tab represents the number of tables you have access to.
- Media: This tab links to the media page and its badge represents the total number of media items within Directus.
- Users: Takes you to the users page.
- Settings: Only visible to admin users, this tab links to the settings page.
- Plugin Tabs: If you have any plugins installed, each will show up as a tab to the right of all standard Directus Tabs. Plugin tabs may also use badges, but you’ll have to read that plugin’s documentation to learn what they represent.
The gateway to Directus. Users provide their username and password to gain access to the Directus CMS. Upon successfully logging in you will be taken to the page you were last on.
Remember Me: If checked, your login credentials will be stored as an encrypted cookie for 30 days of inactivity or until you logout, whichever happens first.
Forgot your password?: If you happen to forget your password retrieving it is easy. Just go to your login page, type your username in the box and hit the “Forgot your password?” button and an email will immediately be sent to you containing your password.
Is a page that houses the activity log as well as a number of other useful modules.
Activity Log: Here you will find an overview of everything that takes place within Directus organized with the most recent events first. Each event has a label denoting what has happened, a clickable title for easy access to the affected item, the user responsible and the precise time the event occurred. Here is a list of possible event labels:
- Blue - Edited, Swapped, Reverted
- Green - Added, Uploaded
- Yellow - Directus/System Events
- Red - Deleted, Deactivated
- Purple - Media
Database Backup: This module allows you to back up your entire database (including the hidden Directus tables) with the click of a button. When pressing the Create New Backup button, Directus will create a file in a backup folder (/directus/inc/backups/) containing all of the SQL code to get you back to this point in the case of an emergency. It also shows the total number of backups available, but as of now does not allow for restoring from within Directus since a careless restore could do a lot of damage.
Example backup file: 2011-04-20_16-20-30_user-name.sql Backup file format: year-month-day_hour-minute-second_username.sql
Note: Although the backup tool may be useful when reverting to previous states of your site, you should be reminded that this tool does not back up or store media leading to it being out of sync with your database state.
Popular Items: This module shows the top 5 most common items in all tables for all users based on the activity log. Clickable for easy access.
This page lists all the tables you have access to and the number of items within each. Some tables are “single” tables and can only hold one item, these are marked with a different icon (). Clicking any table will take you to its browse page except “single” tables which link directly to the edit page. The tables tab badge always shows the total number of tables available to you.
This page let’s you view and interact with all of the items within a table. Clicking on any item will take you to its edit page. Several features available on this page are discussed below:
Add New Item: If your user privileges allow you to add items to this table you will see a large Add New Item button in the top-right of the page. Clicking this will take you to the add page where you can create a new item within this table.
Active, Inactive and Deleted items: Directus allows you to keep items in three different states:
- Active: These are your normal items that are viewable on your website
- Inactive: Similar to a draft mode, these items are not visible on your website
- Deleted: These are items you are no longer using and are not visible on your website
You can change the state of an item by clicking its leftmost checkbox and then clicking one of the three state buttons on the top-left of the page (Active, Inactive or Delete). Checking multiple items allows you to quickly change many items at once, and the checkbox in the column header will toggle all items between checked and unchecked.
Directus has four options for viewing items in their different states on the browse page. This can be changed in the middle dropdown:
- View All: Shows all active and inactive items and is the default option
- View Active: Shows only active items
- View Inactive: Shows only inactive items
- View Trash: Shows only deleted items and does not display item count in the dropdown
To restore an item after it has been deleted, change your viewing option to View Trash and re-activate the item as normal.
Drag-and-Drop Reordering: Directus makes re/ordering your items a breeze. Just grab an item by its handle () and move it to where you’d like it to be. As soon as you let go, Directus will save all visible items on the page with their new order. Using this feature along with the filter feature will allow you to create intricate ordering very quickly.
Sorting: Clicking on any of the column headers will sort all the items within the table based on that field’s data and clicking it again will reverse the sort order. Changing the sort order on this page will not affect the order of items within your website or database (unless you use the drag-and-drop reordering). The leftmost column header (above the item reorder handles) is used by default and orders items by their manual drag-and-drop order. You can also hold the shift key to sort by multiple columns at once.
Choosing column headers: Sometimes your tables will have quite a few fields some of which you might not need to see on this page. At any point you can click the Header Options dropdown to change which fields are visible, this preference is saved for each user so things will always look how you want. Each table has a primary field which can not be hidden.
Filtering: When you have a lot of items in a table it can be helpful to limit what is visible. Typing into the filter field in the top-right of the page will give you immediate results for whatever you are looking for.
Creating email lists: If a field is setup as being for emails (see field options) then you will notice a small email icon in the column header. Clicking this will pop up an alphabetical list of currently visible addresses in a format you can copy and paste into any email client. Using this with the filter feature will enable you to quickly create custom contact lists.
Note: If viewing a “single” table you will skip the browse page since you would only have one option, and instead be taken directly to the edit page.
Note: If the table you are viewing has more than 1000 items, Directus will warn you of possible delays while viewing and interacting with items and Drag-and-Drop Reordering will be turned off.
Edit and Add
These pages are actually the same, but when editing, the fields are filled in with that item’s data. Here that you can create a new item or view/edit an existing item, change its status, delete it or revert it to a previous state. General aspects of this page will be outlined below, for more detailed information on interacting with different field types visit the section on field options.
Item Status: When saving an item you have the option to make it active (default) or inactive which will determine if it will be immediately displayed on your site or put into a draft state. If you are editing an existing item you will also be able to delete the item here.
Item Revisions: This module (below Item Status) expands to show a list of all events for this item including when it was added, edited, reverted or its status was changed and who made the change. Clicking on any of these events will revert the item back to its exact state at that point.
Caution: If you try to edit an item that another user is currently editing you will receive a warning that you should wait until the item is free, otherwise someones changes may be overwritten.
In Directus, all the media you upload or link to can be viewed in one place so you can easily find what you’re looking for and never have to upload the same thing twice. Some file types have special actions available from the media page, these currently include:
Audio and music: These files show the track length and a play/pause button. Clicking the play button will begin playing the track and displays the current time. Currently you can play multiple audio tracks at once. (MP3, OGG and WAV when supported by browser)
Add New Media: Clicking the button in the top-right of the page will open a window where you’re provided with a few options for adding media into Directus. For all options you can choose a title and caption, otherwise Directus will help out.
- Upload from computer: Click the Choose File button and select the file you wish to add.
- Add from URL: Use this option to add media from elsewhere on the web or embed videos. Currently only Vimeo and YouTube are supported and should be added by pasting the full video link into the field:
- Vimeo URL format: http://vimeo.com/18667898
- YouTube URL format: http://www.youtube.com/watch?v=txqiwrbYGrs
Deleting: To delete a media item simply tick its checkbox and click the delete button at the top of the page. Multiple items can be deleted at once by checking several items first. A checkbox in the header column allows you to quickly toggle on and off all media checkboxes.
Caution: Deleting media within Directus does not remove any actual files or update other items linking to that media. Delete with care... media can only be restored at the database level and you will not be warned.
Date Range: This dropdown allows you to view media items that were added to Directus within a specific period. Options are:
- All time: Shows all media (might load slowly if you have a lot of media items)
- Past week: Shows media added in the past week
- Past month: Shows media added in the past month
- Past year: Shows media added in the past year
Note: Over time you might end up with quite a few media items, to speed up load times Directus automatically chooses an appropriate date range to attempt to keep the total media items under 1000. You can of course override this with the date range dropdown.
Filtering: When you have a lot of media it can be helpful to limit what is visible. Typing into the filter field in the top-right of the page will give you immediate results for whatever you are looking for.
Clicking on a media item from within Directus will open up a detail window displaying its information and giving you further options.
Swapping media: Sometimes you will link to a media item throughout Directus and then decide you want to replace the media without losing its connections to other items. To do this, just click the Swap button and you will be given the same options as when you add media normally.
Delete: Just as with the media page, you can delete media from the media detail page.
Caution: Deleting media within Directus does not remove any actual files or update other items linking to that media. Delete with care... media can only be restored at the database level and you will not be warned.
Below are the editable fields within the media detail:
- Name: By default Directus uses the original file name from uploads and video titles from embedded video to create its title... of course you can change it to whatever you’d like.
- Caption: Embed video descriptions are used for captions unless you write one yourself.
- Keywords: Keywords are initially gathered from image meta-data if available and you can always add and remove keywords from there.
Directus also keeps track of a few other useful pieces of information depending on the type of media added including:
- Creator: Who initially added the media item
- Created: When the media item was added
- Modifier: Who last edited the media item
- Modified: When the media item was last modified
- Source: the path to the file including the filename
- Type: The extension of the media item (jpeg is converted to jpg)
- Location: Gathers the address, city, state and country from image meta data
- Date Created: Retrieves the date a photo was taken from its meta data
- Width: The images width in pixels
- Height: The images height in pixels
- File Size: The size of the file in bytes, for embed videos the duration in seconds is stored
Automatic thumbnails are created on the fly when first accessed via URL:
Here you can see all the Directus users in one place with some additional details:
- Avatar: This is either a user uploaded image or the Gravatar associated with their email
- Username: Is bold when the user is currently online. Your username will have an “Edit” button beside it which takes you to your user settings page
- Logged in: When the user wast last online
- Activity: The last page the user was on, or their current page if they are online. Clicking this will take you to that page
- Email: The email address of the user, clicking this will open a new email to that user
- Description: Typically this holds the role or organization of the user, but really you can put anything you want
Note: Inactive users that do not have access to Directus are grayed out and placed at the bottom of the user list.
When you click on the “Edit” button beside your username on the users page or the “User Settings” button in the Directus Header you will be taken to a page that lets you update your personal settings for Directus:
- Username: As a normal user you are not permitted to change your username
- Email: If you forget your password you’ll be happy you set this...
- Email me my new messages: If checked, all Directus messages and replies sent to you will also be forwarded to the email address you set above.
- Password/Confirm: At least 7 characters, allows letters, numbers and _@!#$%^&*
- Description: As mentioned above, this is usually your role within Directus or organization name... but you can enter anything you want
- Avatar: Upload your own photo or check the box to use the Gravatar associated with your email address above
- Can change media: Shows whether you are allowed to add and change media items within Directus. This setting can only be changed by an admin user
- Can send messages: Shows whether you are allowed to send messages within Directus. This setting can only be changed by an admin user
Messages and Inbox
Emails can often get lost or become disorganized in the day-to-day... Directus has a built in messaging system to help you keep all your website or database discussions in one place. Directus messages fall under one of three categories:
- User messages: These are normal messages sent to one, multiple or all other users. They may contain replies from you or any other users in the initial message.
- Item messages: The same as user messages except they are attached to an individual item within Directus. These can be useful when leaving notes or any other item specific comments. They may contain replies from you or any other users in the initial message.
- System messages: When there is a new version or patch to Directus, admin users will receive a message sent from Directus itself detailing the changes made in that version. These messages are all located under a single thread titled “Directus Updates” so they will never take over your inbox.
Archive and Restore: To the right of all Inbox and Sent messages (except replies and System Messages) there is a small “x” button to archive it. Any archived message that is replied to will be automatically moved from your archive into your inbox. When viewing your Archived messages there will be a curvy arrow button that will restore (un-archive) the message.
Each user has three filters for their messages:
- Inbox: Shows all messages sent to you or that you’ve sent which have been replied to by another user. Unread messages and replies are highlighted until viewed and a count of unread messages can be seen from any page as a badge within the Directus Header.
- Sent: Shows all the messages you have sent.
- Archived: Shows all the messages you have deleted
Compose Message: The “Compose Message” button will open up a blank user message. Three things are required for every message:
- Recipient: You can either choose to send your message to “Everyone” or any number of specific users using the checkboxes provided.
- Subject: If you’ve ever sent an email then you already know what this is for. It’s a required field and allows up to 250 characters.
- Message: This is for your message. It’s a required field, and although there’s not really a text limit... try not to bore your recipients.
Note: If you have Email me my new messages turned on within your User Preferences, all new Directus messages will also be forwarded to your email address. At this time you can not respond to Directus messages via email.
Directus has a simple approach to plugins… it provides a way to create pages to do anything you want. Make a custom chart view for your data, a specific data entry method to fulfill your needs or even a project management system. Access all the Directus tables, your own data tables or create new tables just for the plugin (just prepend tables with "directus_" to have them hidden from the rest of the CMS). Basically, there is a plugins folder within every directus install that you can add folders to. These folders (if they have the correct files) each become a plugin tab. It accepts three different files by default:
- index.php Required - Just a simple PHP page that links to the Directus config, header and footer files and has access to the database and all global variables. There is an example file to get you started called "demo_plugin" (just remove the "_off" from the filename).
- plugin_settings.php Optional - If this file is present in your plugin folder, a button called Plugin Settings will appear in your plugin. The page can contain any settings for your plugin (just toss in your PHP)
- info.txt Optional - If this file is present in your plugin folder, a button called Plugin Info will appear in your plugin. This file should be used to describe your plugin, its version, purpose, limitations, developer credit and which version of Directus it's made for.
If you run into problems with Directus at any point, first check here and if you still need help then post a question on
our Help Forum StackOverflow. We have divided the troubleshooting section into two parts, one for admins and another for normal users so as not to overwhelm the latter (or underwhelm the former).
Database error log
Directus provides an error log to help diagnose database problems. Items posted to the error are formatted in the following manner:
2011-04-20 16:20:53 - SQLSTATE[HY000]  Can't connect to MySQL server on 'localhost' (111)