Penpot/penpot
0
Fork 0
mirror of https://github.com/penpot/penpot.git synced 2025-01-21 06:02:32 -05:00
Code Issues Activity

📚 Update documentation.

Browse source
This commit is contained in:
Andrey Antukh 2021-01-27 17:31:17 +01:00
parent fe67bf8fdb
commit 11ff1994f3
9 changed files with 218 additions and 88 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
backend/src/app/cli/fixtures.clj
View file

@ -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)

14
backend/src/app/config.clj
View file

@ -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

6
backend/src/app/http/assets.clj
View file

@ -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]

9
backend/src/app/main.clj
View file

@ -90,9 +90,9 @@
:error-report-handler (ig/ref :app.error-reporter/handler)}
:app.http.assets/handlers
{:metrics (ig/ref :app.metrics/metrics)
:public-uri (:local-assets-uri cfg/config)
:storage (ig/ref :app.storage/storage)
{:metrics (ig/ref :app.metrics/metrics)
:assets-path (:assets-path cfg/config)
: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)

2
backend/src/app/srepl.clj
View file

@ -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}]

5
docker/images/docker-compose.yaml
View file

@ -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_LOCAL_ASSETS_URI=http://penpot-frontend/internal/assets
- PENPOT_STORAGE_FS_DIRECTORY=/opt/data/assets
# Telemetry. When enabled, a periodical process will send
# annonymous data about this instance. Telemetry data will

6
docs/03-Backend-Developer-Guide.md
View file

@ -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

192
docs/05-Configuration-Guide.md Normal file
View file

@ -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

70
docs/05-Management-Guide.md
View file

@ -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=>
```