# BookStack Configuration

## Environment Settings

Bookstack stores custom settings file `.env` within its active directory, `/var/www/bookstack/` this is where you will go to modify most settings within your bookstack instance. Check the GitHub link below for a complete list of environment variables on the active release branch.  

[https://github.com/BookStackApp/BookStack/blob/release/.env.example.complete](https://github.com/BookStackApp/BookStack/blob/release/.env.example.complete)

<p class="callout danger"><code>APP_URL</code> environment variable <span style="text-decoration: underline;">must</span> lead with <code>http://</code> or <code>https://</code> and end with <code>/</code>  
such as <code>http://website.com/</code> or <code>https://website.com/</code>.
Any form of the following will cause URL redirect issues:
<code>www.website.com</code>, <code>website.com</code> or <code>subdomain.website.com</code>
</p>

### Mail Setup

To allow BookStacks to send mail using [Google's free mail server](https://www.digitalocean.com/community/tutorials/how-to-use-google-s-smtp-server), ensure that your .env settings within your bookstack directory ( `/var/www/bookstack/.env` ) contains the below.

    # The below url has to be set if using social auth options
    # or if you are not using BookStack at the root path of your domain.
    APP_URL=https://knoats.com/

    #Mailsettings
    MAIL_DRIVER=smtp
    MAIL_HOST=smtp.gmail.com
    MAIL_PORT=587
    MAIL_USERNAME=email@gmail.com
    MAIL_PASSWORD=password
    MAIL_ENCRYPTION=tls
    MAIL_FROM=email@gmail.com

Now head over to [Configure Postfix](https://www.knoats.com/books/linux-admin/page/configure-postfix) to setup a Mail Transfer Agent (MTA) on your host. If you have a firewall, be sure you open the port you enter for `MAIL_PORT`. 

Once that's done, test sending mail with the command below, where `emailuser@example.com` is the destination email address - 

```bash
echo "This email confirms that Postfix is working" | mail -s "Testing Posfix" emailuser@example.com 
```

You must have a valid HTTPS certificate configured, if you are using DigitalOcean. See the link below.  
[DO - DNS Records](https://www.digitalocean.com/docs/networking/dns/how-to/manage-records/)\
[Knoats - NGINX SSL Configuration](https://www.knoats.com/link/30#bkmrk-configure-ssl)

As a final step, we can use BookStack's builtin mail test within the Settings->Maintenance panel -

[![](https://www.knoats.com/uploads/images/gallery/2020-06/scaled-1680-/image-1591314992713.png)](https://www.knoats.com/uploads/images/gallery/2020-06/image-1591314992713.png)

Once we click the button to send a test email, we should see something like the below

[![](https://www.knoats.com/uploads/images/gallery/2020-06/scaled-1680-/image-1591315123790.png)](https://www.knoats.com/uploads/images/gallery/2020-06/image-1591315123790.png)