Configuration
The two places settings live
Section titled “The two places settings live”| Where | What is there | How to change it |
|---|---|---|
includes/config.local.php | Database connection, the installation secret, and a handful of switches that have to be decided before the database is open. | Edit the file. |
The config database table | Everything else. Company details, currency, tax rates, email, templates, permissions, payment gateway credentials, theme. | The Settings screens in the admin area. |
The settings file
Section titled “The settings file”includes/config.local.php is created by the installer and is the only configuration file you ever edit. It is not part of the download, so an update never overwrites it.
includes/config.php sits next to it and holds the defaults. Do not edit that one — it is replaced every time you update. Anything you want to change, define in config.local.php instead. It is read first, and a value defined there wins.
Database connection
Section titled “Database connection”<?phpdefine( '_DB_SERVER', 'localhost' );define( '_DB_NAME', 'your_database' );define( '_DB_USER', 'your_user' );define( '_DB_PASS', 'your_password' );define( '_DB_PREFIX', 'ucm_' );_DB_SERVER accepts a port as hostname:3306 or a socket path as hostname:/var/run/mysqld/mysqld.sock.
The installation secret
Section titled “The installation secret”define( '_UCM_SECRET', '…64 random hexadecimal characters…' );Every secure link the application generates — invoice payment links, quote approval links, the address of your scheduled task — is signed with this. The installer generates one for you.
If it is not set, the application falls back to using the installation path, which is guessable on shared hosting. Set a real one. Once set, do not change it: changing it invalidates every link already sent to a customer.
Other values you can set
Section titled “Other values you can set”| Constant | Default | What it does |
|---|---|---|
_REWRITE_LINKS | true | Tidy URLs. Set it to false if your server does not rewrite requests — see below. |
_UCM_FILE_STORAGE_DIR | the installation folder | Where uploads, backups, generated PDFs and session files are written. An absolute path with a trailing slash. See below. |
_UCM_FILE_STORAGE_HREF | the site address | The web address that corresponds to the folder above. Only needed if you change it. |
_DEBUG_MODE | false | Shows PHP errors on screen and adds a timing panel at the foot of each page. Useful for diagnosing a problem; never leave it on for a live site. |
_DEBUG_SQL | false | Adds every database query to that panel. Only has an effect when _DEBUG_MODE is also on. |
_BLOCK_EMAILS | false | Stops all outgoing email. Set this on a copy of a live site so that testing cannot mail your real customers. |
_CUSTOM_UCM_HOMEPAGE | not set | Send anyone arriving at the root of the site to this address instead of the dashboard. |
_UCM_HIDE_UPGRADE | not set | Define it to hide and block the built-in upgrade screen. Useful if you manage updates yourself. |
_UCM_HIDE_BACKUPS | not set | Define it to hide and block the backup screen. |
Setting values from the environment instead
Section titled “Setting values from the environment instead”If you deploy with a script, or to a platform where writing files is awkward, these environment variables are read before the file: UCM_DB_SERVER, UCM_DB_NAME, UCM_DB_USER, UCM_DB_PASS, UCM_DB_PREFIX, UCM_SECRET, and UCM_CONFIG_LOCAL to point the settings file somewhere else entirely. UCM_DEBUG turns error display on.
Moving file storage outside the web root
Section titled “Moving file storage outside the web root”By default everything uploaded is stored inside your web space, protected by .htaccess rules. If you would rather have it somewhere the web server cannot reach at all, set:
define( '_UCM_FILE_STORAGE_DIR', '/home/youraccount/ucm-files/' );Create that folder and make it writable by PHP. The application creates the subfolders it needs. Move your existing files across before switching, or they will appear to vanish.
Tidy URLs
Section titled “Tidy URLs”By default the application produces addresses like /customer.customer_admin/ rather than /?m=customer&p=customer_admin. This relies on the web server sending every request that is not a real file to index.php, which the included .htaccess arranges on Apache.
On nginx, or on an Apache server without mod_rewrite, that does not happen and every link in the application gives a 404. There are two fixes:
- Preferred: configure the rewrite in your server config. On nginx, route anything that is not an existing file or directory to
index.php. - Otherwise: add
define( '_REWRITE_LINKS', false );toincludes/config.local.php. Links fall back to the query string form, which needs no rewriting at all. Everything works; the addresses are just uglier.
There is no setting for this in the admin area — it has to go in the file, because it is needed before any page is built.
The Settings screens
Section titled “The Settings screens”Everything else is in the admin area under Settings. The main areas:
| Screen | What it covers |
|---|---|
| System Settings | Company name and address, the site address, currency, date format, timezone, and the administrator email that system notices go to. Set this up first — it feeds invoices, quotes and every email template. |
| Whether to use SMTP or the server’s own mail, SMTP credentials, encryption, and sending limits. There is a test sender on this screen. | |
| Payment Methods | Which methods customers are offered and the credentials for each. See Payment methods. |
| Users | Staff and customer accounts, and their passwords. |
| User Roles | Roles and per-feature permissions. Each plugin contributes its own permissions, so this list grows with what you have switched on. |
| Templates | The wording of every email the system sends, and the layouts used for invoices and quotes. |
| Theme | Which of the included themes to use, and a box for your own CSS. See Customising. |
| Languages | Translating the interface. See below. |
| Cron | Shows the exact command and the web address for your scheduled task. See Scheduled tasks. |
| Backup | Database and file backups, if the zip extension is available. |
| Upgrade | Runs database upgrades after a file update, and checks for new versions. |
Currency, tax and dates
Section titled “Currency, tax and dates”Currency and tax are per-installation defaults set under System Settings, with per-invoice overrides where that makes sense. If you invoice in more than one currency, add the extra currencies first — they appear as a choice on each invoice afterwards.
Date format is a display preference and changing it does not alter stored data, so it is safe to change at any time.
Languages
Section titled “Languages”The interface text runs through a translation layer, so it can be translated without editing any code. Settings → Language lists the strings the application has seen and lets you supply replacements.
Translations you add are stored in the database. You can also drop PHP language files into includes/plugin_language/custom/, which is a separate mechanism from the custom/ override folder described in Customising — do not confuse the two.
Email sending
Section titled “Email sending”Two modes:
- The server’s own mail. The default. Nothing to configure. Works on many hosts, and on others is silently dropped or goes to spam.
- SMTP. Tick Use SMTP and give a hostname, username, password and encryption type. Choose TLS for most providers. This is more reliable and much better for deliverability, because the mail is then sent by a server that is allowed to send as your domain.
There is a sending rate limit on the same screen, expressed as a number per minute, hour or day. Set it to match whatever your provider allows, or large newsletter sends will be rejected partway through.
Always use the test sender after changing anything here. If the test arrives and real notifications do not, the problem is the template or the trigger, not the mail settings.