Configuration and getting started

introduction

There are a few settings you will need to configure in the PuckWeb project appSettings.json file.

1. connection string

you will need to point the provider specific connection string property to your database. SQL Server, PostgreSQL, MySQL and SQLite are supported.

2. setting initial user email and password

you will need to modify the InitialUserEmail and InitialUserPassword AppSettings. this will be used to setup the initial admin user for Puck.

creating the database

you will need to add your provider specific database connection string in your appsettings.json. there are connection string placeholder properties in the appsettings.json for SQLServer, PostgreSQL, MySQL and SQLite - set the appropriate property. there is also a boolean flag you set to specify which database you are using, so if you're using SQL Server, set UseSQLServer to true and make sure that UsePostgreSQL,UseMySQL and UseSQLite properties are set to false. you can then run the application and it will run an entity framework migration on app start to create the database.

if you want to migrate manually, you will need to run update-database -Context <Context> (where Context is either PuckContextSQLServer, PuckContextPostgreSQL, PuckContextMySQL or PuckContextSQLite) in the package manager console targeting the core project to create the database. there is a seed task that will run on app startup using the InitialUserEmail and InitialUserPassword settings you configured to create the initial user and add all CMS roles to the user.

Logging in to the backoffice

once you have the site running, you can go to the admin section. the admin path is /puck/ and you will need to log in using the InitialUserEmail and InitialUserPassword you configured in the appsettings.json. you can then set your languages and start creating content.

additional configuration

1. if you want to enable content notifications (ie edit, publish, delete, move) then you need to enter all the Smtp settings, here is an example:

  "SmtpHost": "smtp.sendgrid.net",
  "SmtpPort": 587,
  "SmtpUserName": "apikey",
  "SmtpPassword": "<password>",
  "SmtpUseSsl": false,
  "SmtpFrom": "puck@localhost"

2. if you plan on storing your images in azure, set the AzureImageTransformer_AccountName and AzureImageTransformer_AccessKey AppSettings. to minimise customisation, you can leave AzureImageTransformer_ContainerName set as "azure".

Lucene index location

there are several lucene related app settings, let's start with the default setup:

"LuceneIndexPath": "~/App_Data/Lucene{machinename}",
"LuceneAzureIndexPath": "D:\\local\\Temp\\Lucene",
"UseAzureLucenePath": false,

the LuceneIndexPath app setting determines the location of the Lucene index. you can add the token "{machinename}" - for example: ~/App_Data/Lucene{machinename} to your path and this will be replaced with a server specific identifier. this is useful for environments with shared file system where multiple servers/workers are sharing the same disk - each worker will get a different lucene index and this will prevent file lock issues.

azure is one such environment and you can set the UseAzureLucenePath app setting to "true" when working in azure to use a temporary file location local to each worker instance. because azure temp file is local to each worker and not shared, you should not add the "{machinename}" token to LuceneAzureIndexPath.

using Azure Directory

if you don't use Azure Directory and instead set UseAzureLucenePath to true, the lucene indexes will be rebuilt every time the app restarts which will cause a delay when starting up. to prevent the need to re-index every time the app starts, you can use Azure Directory by setting UseAzureDirectory to true and then setting AzureDirectoryConnectionString to a valid Azure Blob Storage connection string.