📚 Update documentation.

backend/src/app/cli/fixtures.clj

@@ -82,7 +82,7 @@
                                             :fullname (str "Profile " index)
                                             :password "123123"
                                             :demo? true
-                                            :email (str "profile" index ".test@penpot.app")})
+                                            :email (str "profile" index "@example.com")})
                     team-id  (:default-team-id prof)
                     owner-id id]
                 (let [project-ids (collect (partial create-project conn team-id owner-id)

backend/src/app/config.clj

@@ -20,6 +20,7 @@
 (def defaults
   {:http-server-port 6060
    :http-server-cors "http://localhost:3449"
+
    :database-uri "postgresql://127.0.0.1/penpot"
    :database-username "penpot"
    :database-password "penpot"
@@ -29,13 +30,16 @@
    :public-uri "http://localhost:3449"
    :redis-uri "redis://localhost/0"
 
+   :srepl-host "127.0.0.1"
+   :srepl-port 6062
+
    :storage-backend :fs
 
    :storage-fs-directory "resources/public/assets"
    :storage-s3-region :eu-central-1
    :storage-s3-bucket "penpot-devenv-assets-pre"
 
-   :local-assets-uri "http://localhost:3449/internal/assets/"
+   :assets-path "/internal/assets/"
 
    :rlimits-password 10
    :rlimits-image 2
@@ -82,7 +86,7 @@
 
 (s/def ::storage-backend ::us/keyword)
 (s/def ::storage-fs-directory ::us/string)
-(s/def ::local-assets-uri ::us/string)
+(s/def ::assets-path ::us/string)
 (s/def ::storage-s3-region ::us/keyword)
 (s/def ::storage-s3-bucket ::us/string)
 
@@ -106,7 +110,9 @@
 (s/def ::registration-domain-whitelist ::us/string)
 (s/def ::debug ::us/boolean)
 (s/def ::public-uri ::us/string)
-(s/def ::backend-uri ::us/string)
+
+(s/def ::srepl-host ::us/string)
+(s/def ::srepl-port ::us/integer)
 
 (s/def ::rlimits-password ::us/integer)
 (s/def ::rlimits-image ::us/integer)
@@ -190,6 +196,8 @@
                    ::smtp-username
                    ::storage-backend
                    ::storage-fs-directory
+                   ::srepl-host
+                   ::srepl-port
                    ::local-assets-uri
                    ::storage-s3-bucket
                    ::storage-s3-region

backend/src/app/http/assets.clj

@@ -64,7 +64,7 @@
          :body ""})
 
       :fs
-      (let [purl (u/uri (:public-uri cfg))
+      (let [purl (u/uri (:assets-path cfg))
             purl (u/join purl (sto/object->relative-path obj))]
         {:status 204
          :headers {"x-accel-redirect" (:path purl)
@@ -100,12 +100,12 @@
 ;; --- Initialization
 
 (s/def ::storage some?)
-(s/def ::public-uri ::us/string)
+(s/def ::assets-path ::us/string)
 (s/def ::cache-max-age ::dt/duration)
 (s/def ::signature-max-age ::dt/duration)
 
 (defmethod ig/pre-init-spec ::handlers [_]
-  (s/keys :req-un [::storage ::mtx/metrics ::public-uri ::cache-max-age ::signature-max-age]))
+  (s/keys :req-un [::storage ::mtx/metrics ::assets-path ::cache-max-age ::signature-max-age]))
 
 (defmethod ig/init-key ::handlers
   [_ cfg]

backend/src/app/main.clj

@@ -90,9 +90,9 @@
      :error-report-handler (ig/ref :app.error-reporter/handler)}
 
     :app.http.assets/handlers
-    {:metrics    (ig/ref :app.metrics/metrics)
+    {:metrics           (ig/ref :app.metrics/metrics)
-     :public-uri (:local-assets-uri cfg/config)
+     :assets-path       (:assets-path cfg/config)
-     :storage    (ig/ref :app.storage/storage)
+     :storage           (ig/ref :app.storage/storage)
      :cache-max-age     (dt/duration {:hours 24})
      :signature-max-age (dt/duration {:hours 24 :minutes 5})}
 
@@ -262,7 +262,8 @@
      :uri         (:telemetry-uri cfg/config)}
 
     :app.srepl/server
-    {:port 6062}
+    {:port (:srepl-port cfg/config)
+     :host (:srepl-host cfg/config)}
 
     :app.error-reporter/reporter
     {:uri      (:error-report-webhook cfg/config)

backend/src/app/srepl.clj

@@ -40,7 +40,7 @@
 
 (defmethod ig/prep-key ::server
   [_ cfg]
-  (merge {:port 6062 :host "127.0.0.1" :name "main"} cfg))
+  (merge {:name "main"} cfg))
 
 (defmethod ig/init-key ::server
   [_ {:keys [port host name] :as cfg}]

docker/images/docker-compose.yaml

@@ -38,7 +38,7 @@ services:
 
       # Should be set to the public domain when penpot is going to be
       # served.
-      - PENPOT_PUBLIC_URI=http://localhost
+      - PENPOT_PUBLIC_URI=http://localhost:9001
 
       # Standard database connection parametes (only postgresql is supported):
       - PENPOT_DATABASE_URI=postgresql://penpot-postgres/penpot
@@ -54,8 +54,7 @@ services:
       # the backups more easy but will make access to media less
       # performant.
       - PENPOT_STORAGE_BACKEND=fs
-      - PENPOT_STORAGE_FS_DIRECTORY_=/opt/data/assets
+      - PENPOT_STORAGE_FS_DIRECTORY=/opt/data/assets
-      - PENPOT_LOCAL_ASSETS_URI=http://penpot-frontend/internal/assets
 
       # Telemetry. When enabled, a periodical process will send
       # annonymous data about this instance. Telemetry data will

docs/03-Backend-Developer-Guide.md

@@ -25,10 +25,10 @@ empty database.
 This by default will create a bunch of users that can be used to login
 in the aplication. All users uses the following pattern:
 
-- Username: `profileN.test@uxbox.io`
+- Username: `profileN@example.com`
 - Password: `123123`
 
-Where `N` is a number from 0 to 49 on the default fixture parameters.
+Where `N` is a number from 0 to 5 on the default fixture parameters.
 
 If you have a REPL access to the running process, you can execute it
 from there:
@@ -42,7 +42,7 @@ To access to the running process repl you usually will execute this
 command:
 
 ```bash
-rlwrap netcat localhost 5555
+rlwrap netcat localhost 6062
 ```
 
 ## Migrations

docs/05-Configuration-Guide.md

@@ -0,0 +1,192 @@
+# Configuration Guide #
+
+This section intends to explain all available configuration options.
+
+## Backend ##
+
+The default approach for pass options to backend application is using
+environment variables. Almost all environment variables starts with
+the `PENPOT_` prefix.
+
+NOTE: All the examples that comes with values, they represent the
+**default** values.
+
+
+### Configuration Options
+
+
+#### Database Connection
+
+```sh
+PENPOT_DATABASE_USERNAME=penpot
+PENPOT_DATABASE_PASSWORD=penpot
+PENPOT_DATABASE_URI=postgresql://127.0.0.1/penpot
+```
+
+The username and password are optional.
+
+#### Email (SMTP)
+
+```sh
+PENPOT_SMTP_DEFAULT_REPLY_TO=no-reply@example.com
+PENPOT_SMTP_DEFAULT_FROM=no-reply@example.com
+
+# When not enabled, the emails are printed to the console.
+PENPOT_SMTP_ENABLED=false
+
+PENPOT_SMTP_HOST=<host>
+PENPOT_SMTP_PORT=25
+PENPOT_SMTP_USER=<username>
+PENPOT_SMTP_PASSWORD=<password>
+PENPOT_SMTP_SSL=false
+PENPOT_SMTP_TLS=false
+```
+
+#### Storage (assets)
+
+Assets storage is implemented using "plugable" backends. Currently
+there are three backends available: `db`, `fs` and `s3` (for AWS S3).
+
+##### fs backend
+
+The default backend is: **fs**.
+
+```sh
+PENPOT_STORAGE_BACKEND=fs
+PENPOT_STORAGE_FS_DIRECTORY=resources/public/assets`
+```
+
+The fs backend is hightly coupled with nginx way to serve files using
+`x-accel-redirect` and for correctly configuring it you will need to
+touch your nginx config for correctly expose the directory specified
+in `PENPOT_STORAGE_FS_DIRECTORY` environment.
+
+For more concrete example look at the devenv nginx configurtion
+located in `<repo-root>/docker/devenv/files/nginx.conf`.
+
+**NOTE**: The **fs** storage backend is used for store temporal files
+when a user uploads an image and that image need to be processed for
+creating thumbnails. So is **hightly recommeded** setting up a correct
+directory for this backend independently if it is used as main backend
+or not.
+
+##### db backend
+
+In some circumstances or just for convenience you can use the `db`
+backend that stores all media uploaded by the user directly inside the
+database. This backend, at expenses of some overhead, facilitates the
+backups, because with this backend all that you need to backup is the
+postgresql database. Convenient for small installations and personal
+use.
+
+```sh
+PENPOT_STORAGE_BACKEND=db
+```
+
+
+##### s3 backend
+
+And finally, you can use AWS S3 service as backend for assets
+storage. For this you will need to have AWS credentials, an bucket and
+the region of the bucket.
+
+```sh
+AWS_ACCESS_KEY_ID=<you-access-key-id-here>
+AWS_SECRET_ACCESS_KEY=<your-secret-access-key-here>
+PENPOT_STORAGE_BACKEND=s3
+PENPOT_STORAGE_S3_REGION=<aws-region>
+PENPOT_STORAGE_S3_BUCKET=<bucket-name>
+```
+
+Right now, only `eu-central-1` region is supported. If you need others, open an issue.
+
+#### Redis
+
+The redis configuration is very simple, just provide with a valid redis URI. Redis is used
+mainly for websocket notifications coordination.
+
+```sh
+PENPOT_REDIS_URI=redis://localhost/0
+```
+
+
+#### HTTP Server
+
+```sh
+PENPOT_HTTP_SERVER_PORT=6060
+PENPOT_PUBLIC_URI=http://localhost:3449
+PENPOT_REGISTRATION_ENABLED=true
+
+# comma-separated domains, defaults to `""` which means that all domains are allowed)
+PENPOT_REGISTRATION_DOMAIN_WHITELIST=""
+```
+
+#### Server REPL
+
+The production environment by default starts a server REPL where you
+can connect and perform diagnosis operations. For this you will need
+`netcat` or `telnet` installed in the server.
+
+```bash
+$ rlwrap netcat localhost 6062
+user=>
+```
+The default configuration is:
+
+```sh
+PENPOT_SREPL_HOST=127.0.0.1
+PENPOT_SREPL_PORT=6062
+```
+
+#### Auth with 3rd party
+
+**NOTE**: a part of setting this configuration on backend, frontend
+application will also require configuration tweaks for make it work.
+
+##### Goolge
+
+```
+PENPOT_GOOGLE_CLIENT_ID=<client-id>
+PENPOT_GOOGLE_CLIENT_SECRET=<client-secret>
+```
+
+##### Gitlab
+
+```
+PENPOT_GITLAB_BASE_URI=https://gitlab.com
+PENPOT_GITLAB_CLIENT_ID=<client-id>
+PENPOT_GITLAB_CLIENT_SECRET=<client-secret>
+```
+
+##### Github
+
+```
+PENPOT_GITHUB_CLIENT_ID=<client-id>
+PENPOT_GITHUB_CLIENT_SECRET=<client-secret>
+```
+
+##### LDAP
+
+```
+PENPOT_LDAP_AUTH_HOST=     (default undefined)
+PENPOT_LDAP_AUTH_PORT=     (default undefined)
+PENPOT_LDAP_AUTH_VERSION=3
+PENPOT_LDAP_BIND_DN=       (default undefined)
+PENPOT_LDAP_BIND_PASSWORD= (default undefined)
+PENPOT_LDAP_AUTH_SSL=      (default false)
+PENPOT_LDAP_AUTH_STARTTLS= (default false)
+PENPOT_LDAP_AUTH_BASE_DN=  (default undefined)
+PENPOT_LDAP_AUTH_USER_QUERY=(|(uid=$username)(mail=$username))
+PENPOT_LDAP_AUTH_USERNAME_ATTRIBUTE=uid
+PENPOT_LDAP_AUTH_EMAIL_ATTRIBUTE=mail
+PENPOT_LDAP_AUTH_FULLNAME_ATTRIBUTE=displayName
+PENPOT_LDAP_AUTH_AVATAR_ATTRIBUTE=jpegPhoto
+```
+
+## Frontend ##
+
+TODO
+
+## Exporter ##
+
+TODO

docs/05-Management-Guide.md

@@ -1,70 +0,0 @@
-# Management Guide #
-
-**TODO**
-
-## Frontend configuration parameters ##
-
-Not needed.
-
-
-## Backend configuration parameters ##
-
-Backend accepts a bunch of configuration parameters (detailed above),
-that can be passed in different ways. The preferred one is using
-environment variables.
-
-This is a probably incomplete list of available options (with
-respective defaults):
-
-- `PENPOT_HTTP_SERVER_PORT=6060`
-- `PENPOT_PUBLIC_URI=http://localhost:3449`
-- `PENPOT_DATABASE_USERNAME=<username>`
-- `PENPOT_DATABASE_PASSWORD=<password>`
-- `PENPOT_DATABASE_URI=postgresql://127.0.0.1/penpot`
-- `PENPOT_STORAGE_FS_DIRECTORY=resources/public/assets`
-- `PENPOT_LOCAL_ASSETS_URI=http://localhost:6060/assets/internal`
-- `PENPOT_SMTP_DEFAULT_REPLY_TO=no-reply@example.com`
-- `PENPOT_SMTP_DEFAULT_FROM=no-reply@example.com`
-- `PENPOT_SMTP_ENABLED=`  (default false, prints to console)
-- `PENPOT_SMTP_HOST=`     (default undefined)
-- `PENPOT_SMTP_PORT=`     (default undefined)
-- `PENPOT_SMTP_USER=`     (default undefined)
-- `PENPOT_SMTP_PASSWORD=` (default undefined)
-- `PENPOT_SMTP_SSL=`      (default to `false`)
-- `PENPOT_SMTP_TLS=`      (default to `false`)
-- `PENPOT_REDIS_URI=redis://localhost/0`
-- `PENPOT_REGISTRATION_ENABLED=true`
-- `PENPOT_REGISTRATION_DOMAIN_WHITELIST=""` (comma-separated domains, defaults to `""` which means that all domains are allowed)
-- `PENPOT_DEBUG=true`
-
-- `PENPOT_LDAP_AUTH_HOST=`     (default undefined)
-- `PENPOT_LDAP_AUTH_PORT=`     (default undefined)
-- `PENPOT_LDAP_AUTH_VERSION=3`
-- `PENPOT_LDAP_BIND_DN=`       (default undefined)
-- `PENPOT_LDAP_BIND_PASSWORD=` (default undefined)
-- `PENPOT_LDAP_AUTH_SSL=`      (default `false`)
-- `PENPOT_LDAP_AUTH_STARTTLS=` (default `false`)
-- `PENPOT_LDAP_AUTH_BASE_DN=`  (default undefined)
-- `PENPOT_LDAP_AUTH_USER_QUERY=(|(uid=$username)(mail=$username))`
-- `PENPOT_LDAP_AUTH_USERNAME_ATTRIBUTE=uid`
-- `PENPOT_LDAP_AUTH_EMAIL_ATTRIBUTE=mail`
-- `PENPOT_LDAP_AUTH_FULLNAME_ATTRIBUTE=displayName`
-- `PENPOT_LDAP_AUTH_AVATAR_ATTRIBUTE=jpegPhoto`
-
-- `PENPOT_GITLAB_CLIENT_ID=`     (default undefined)
-- `PENPOT_GITLAB_CLIENT_SECRET=` (default undefined)
-- `PENPOT_GITLAB_BASE_URI=`      (default https://gitlab.com)
-
-- `PENPOT_GITHUB_CLIENT_ID=`     (default undefined)
-- `PENPOT_GITHUB_CLIENT_SECRET=` (default undefined)
-
-## REPL ##
-
-The production environment by default starts a server REPL where you
-can connect and perform diagnosis operations. For this you will need
-`netcat` or `telnet` installed in the server.
-
-```bash
-$ rlwrap netcat localhost 6062
-user=>
-```