presentator

README

Presentator is free and open source design feedback and presentation platform.

It can be used directly via the free hosted service at app.presentator.io or self host it on your own server via a single executable.

• Local setup
• Configurations
• Going to production
• Updating
• Extending
• Contributing
• Security

Local setup

1. Download the prebuilt executable for your platform from the Releases page.

2. Start the executable from the terminal:

   # run `./presentator --help` for all available commands and options
   ./presentator serve
   

3. Navigate to http://127.0.0.1:8090/_/ to access the super admin dashboard (PocketBase).

   The first time when you access /_/ it will prompt you to create a super-admin account in order to configure various application settings like SMTP, files storage, OAuth2, etc. (see Configurations).

And that's it. By default your settings and db data will be stored in the pb_data directory next to the executable.

Once done with the configurations, you can create a new user from the PocketBase dashboard or navigate to http://127.0.0.1:8090/ to register as regular user.

Configurations

SMTP

In order to send emails you'll have to use either a local SMTP server or an external mail service like Mailjet, MailerSend, Brevo, SendGrid, AWS SES, etc.

Once you've decided on a mail service, you could enable the SMTP settings from your PocketBase Admin UI > Settings > Mail settings page (http://localhost:8090/_/#/settings/mail).

Make sure to update also the "Application URL" field located in Settings > Application.

S3 files storage

By default Presentator uses the local filesystem to store uploaded files. If you have limited disk space and plan to store a lot of files, you can use an external S3 compatible storage. This could be done from your PocketBase Admin UI > Settings > Files storage page (http://127.0.0.1:8090/_/#/settings/storage).

OAuth2 authentication

Presentator supports various OAuth2 providers - Google, Microsoft, Facebook, GitHub, Gitlab, etc. OAuth2 providers can be enabled from your PocketBase Admin UI > Settings > Auth providers page (http://127.0.0.1:8090/_/#/settings/auth-providers).

For OAuth2 redirect url/callback you must use https://yourdomain.com/api/oauth2-redirect.

[!NOTE] By default Presentator users are required to have an email so providers that don't return an email will fail to authenticate.

Increase allowed screens upload size

By default uploaded screen images are limited to ~7MB max. The default should be sufficient for most users but if you need to upload larger screens you can increase the limit from your PocketBase Admin UI:

1. Temporary enable the Collections create/edit controls from PocketBase Admin UI > Settings > Application > "Hide collection create and edit controls" toggle (http://127.0.0.1:8090/_/#/settings).
2. Navigate to PocketBase Admin UI > Collections > screens > "Edit collection" cogwheel and click on the file field options to update the "Max file size" input.
3. Enable back the "Hide collection create and edit controls" toggle from 1) to prevent accidental schema changes.

Custom terms page url

To specify a "Terms and Conditions" url, that is referenced during the users registration, you can use the --termsUrl flag when starting the prebuilt executable:

./presentator serve --termsUrl='https://example.com/terms-and-conditions'

Custom footer links

To specify footer links (ex. privacy policies, contacts, etc.), you can use the --footerLinks flag when starting the prebuilt executable:

# comma separated footer links in the format 'title1|url1, title2|url2, ...'
# (use --help for more details)
./presentator serve --footerLinks='Contacts|https://example.com/contacts'

[!NOTE] Support for changing the primary colors, logo, etc. of the Presentator UI will be added in the future once custom PocketBase Admin UI settings are implemented.

Going to production

Deploying your configured local Presentator to a production environment is the same as deploying a PocketBase application.

For simplicity here is one minimal example how to deploy to a Linux server:

1. Consider the following app directory structure:

   presentatordir/
       pb_data/
       presentator
   

2. Upload the Presentator executable (make sure that it is suitable for your server architecture) and the pb_data directory to your remote server, for example using rsync:

   rsync -avz -e ssh /local/path/to/presentatordir/ root@YOUR_SERVER_IP:/root/pr
   

3. Start a SSH session with your server:

   ssh root@YOUR_SERVER_IP
   

4. Start the executable and specify a domain name so that the application can automatically issue a Let's encrypt certificate (it will bind to 80 and 443 ports):

   [root@dev ~]$ /root/pr/presentator serve yourdomain.com
   

5. (Optional) You can skip step 3 and create a Systemd service to allow your application to start/restart on its own. Here is an example service file (usually created in /lib/systemd/system/presentator.service):

   [Unit]
   Description = presentator
   
   [Service]
   Type           = simple
   User           = root
   Group          = root
   LimitNOFILE    = 4096
   Restart        = always
   RestartSec     = 5s
   StandardOutput = append:/root/pr/errors.log
   StandardError  = append:/root/pr/errors.log
   ExecStart      = /root/pr/presentator serve yourdomain.com
   
   [Install]
   WantedBy = multi-user.target
   

   After that we just have to enable it and start the service using systemctl:

   [root@dev ~]$ systemctl enable presentator.service
   [root@dev ~]$ systemctl start presentator
   

If you want to deploy Presentator behind a reverse proxy (nginx, apache, caddy, etc.), please refer to the PocketBase - Going to production docs.

Updating

To update the prebuilt Presentator v3 executable it is enough to run ./presentator update. The command will create automatically a snapshot/backup of your pb_data (you can disable this with the --backup=0 flag).

If you use Presentator v2 and want to upgrade to v3, please follow the instructions in presentator/v2tov3migrate.

Extending

Because Presentator is based on PocketBase, it can be extended in a similar manner using Go or JS.

[!WARNING] Keep in mind that PocketBase in still in active development and there is no backward guarantee before reaching v1.

Extend with JS

To extend with JS, it is enough to create pb_hooks/*.pb.js file(s) next to your executable and restart the application.

For example, here is a pb_hooks/main.pb.js hook that will print in the console the comment message after its creation:

// pb_hooks/main.pb.js
/// <reference path="../pb_data/types.d.ts" />

onRecordAfterCreateRequest((e) => {
    console.log(e.record.get("message"))
}, "comments");

For more details about the available hooks and methods, please refer to PocketBase - Extend with JS.

Extend with Go

Presentator is also distributed as regular Go package allowing you to extend it with custom functionality using the exposed Go APIs.

1. Install Go 1.22+

2. Create a new project directory with myapp/main.go file inside it. Here is one minimal main.go file with a hook that will print in the console the comment message after its creation:

   package main
   
   import (
       "log"
   
       "github.com/pocketbase/pocketbase/core"
       "github.com/presentator/presentator/v3"
   )
   
   func main() {
       // see https://pkg.go.dev/github.com/presentator/presentator
       pr := presentator.New()
   
       pr.OnRecordAfterCreateRequest("comments").Add(func(e *core.RecordCreateEvent) error {
           log.Println(e.Record.GetString("message"))
           return nil
       })
   
       if err := pr.Start(); err != nil {
           log.Fatal(err)
       }
   }
   

3. To init the dependencies, run go mod init myapp && go mod tidy.

4. To start the application, run go run . serve.

5. To build a statically linked executable, you can run CGO_ENABLED=0 go build and then start the created executable with ``./myapp serve`.

You can also use the prebuilt executable main.go file as a reference located in base/main.go.

For more details about the available hooks and methods, please refer to PocketBase - Extend with Go.

Contributing

Presentator is free and open source project licensed under the BSD 3-Clause License.

Presentator is not a business and it doesn't have any monetization plans. It is developed entirely on volunteer basis mostly by me. Therefore to avoid the project getting too complex and unwieldy, I may not always be open for expanding its scope and I may reject your suggestion if I don't think I'll have the time to develop and maintain the requested feature.

With that said, you could help by:

• Report issues and fix bugs
• Donate a small amount to keep the free hosting service alive

Security

If you discover a security vulnerability within Presentator or its services, please send an email to support at presentator.io.

All reports will be promptly addressed, and you'll be credited accordingly.

Documentation

Index

• Constants
• type Presentator
  • func New() *Presentator
• type ReportForm
  • func (form *ReportForm) Submit() error
  • func (form *ReportForm) Validate() error
• type SettingsValidator
• type ShareForm
  • func (form *ShareForm) Submit() error
  • func (form *ShareForm) Validate() error

Constants

const (
	OptionFooterLinks      string = "pr_footerLinks"
	OptionTermsUrl         string = "pr_termsUrl"
	OptionAllowHotspotsUrl string = "pr_allowHotspotsUrl"
)

@todo remove after adding support for custom Admin UI settings fields.

Types

type Presentator

type Presentator struct {
	*pocketbase.PocketBase
}

func New

func New() *Presentator

type ReportForm

type ReportForm struct {
	Message string `form:"message" json:"message"`
	// contains filtered or unexported fields
}

ReportForm handles a design report submission.

func (*ReportForm) Submit

func (form *ReportForm) Submit() error

Submit validates the form and send a report email.

func (*ReportForm) Validate

func (form *ReportForm) Validate() error

Validate makes the form validatable by implementing validation.Validatable interface.

type SettingsValidator

type SettingsValidator interface {
	Validate(app core.App) error
}

type ShareForm

type ShareForm struct {
	Message string   `form:"message" json:"message"`
	Emails  []string `form:"emails" json:"emails"`
	// contains filtered or unexported fields
}

ShareForm handles a single link share submission.

func (*ShareForm) Submit

func (form *ShareForm) Submit() error

Submit validates the form and send an email with the project link to each form.Emails.

If an error occur during the mail submission the operation doesn't stop. All mail send failures are returned as a single joined error.

func (*ShareForm) Validate

func (form *ShareForm) Validate() error

Validate makes the form validatable by implementing validation.Validatable interface.