Maintenance: Enable Markdown linting and adjust content.
Co-authored-by: Dusan Vuckovic <dv@zammad.com> Co-authored-by: Ralf Schmid <rsc@zammad.com>
This commit is contained in:
Ralf Schmid
@@ -2,28 +2,35 @@
|
||||
|
||||
## Updating Image Snapshots
|
||||
|
||||
This command only _updates_ snapshots. Cypress will run only tests with `*-visual.cy` in their name, and will not fail, if snapshot is not correct, but will generate a new snapshot instead.
|
||||
This command only _updates_ snapshots. Cypress will run only tests with `*-visual.cy` in their name, and will not fail,
|
||||
if snapshot is not correct, but will generate a new snapshot instead.
|
||||
|
||||
```sh
|
||||
# from the root directory
|
||||
$ pnpm cypress:snapshots
|
||||
pnpm cypress:snapshots
|
||||
```
|
||||
|
||||
Please, make sure snapshot is actually correct before pushing your changes.
|
||||
|
||||
## Running Tests
|
||||
|
||||
Although you may run visual tests using `pnpm test:ci:ct` command, this will execute them in your current development environment. However, stored image snapshots were generated in Docker containers in order to achieve consistent environment every time. Due to multiple factors (i.e. screen density, font resolution, browser version, etc), your mileage may vary and you may receive false negatives.
|
||||
Although you may run visual tests using `pnpm test:ci:ct` command, this will execute them in your current development
|
||||
environment. However, stored image snapshots were generated in Docker containers in order to achieve consistent
|
||||
environment every time. Due to multiple factors (i.e. screen density, font resolution, browser version, etc), your
|
||||
mileage may vary and you may receive false negatives.
|
||||
|
||||
It is therefore advisable to run the visual regression tests in the same environment where the image snapshots are normally updated. You can do this by setting an environment variable and running the snapshots command:
|
||||
It is therefore advisable to run the visual regression tests in the same environment where the image snapshots are
|
||||
normally updated. You can do this by setting an environment variable and running the snapshots command:
|
||||
|
||||
```sh
|
||||
# from the root directory
|
||||
$ CYPRESS_UPDATE_SNAPSHOTS=false pnpm cypress:snapshots
|
||||
CYPRESS_UPDATE_SNAPSHOTS=false pnpm cypress:snapshots
|
||||
```
|
||||
|
||||
## Multiple Architecture (AMD64 vs ARM)
|
||||
|
||||
Cypress doesn't work inside amd64 image, if it's running on ARM processor, even under `--platform=linux/amd64`. So we have two compose files, and based on user processor we run one or the other.
|
||||
Cypress doesn't work inside amd64 image, if it's running on ARM processor, even under `--platform=linux/amd64`. So we
|
||||
have two compose files, and based on user processor we run one or the other.
|
||||
|
||||
ARM compose file has a custom cache folder, so it doesn't conflict with Mac's usual `~/Library/Cache` folder. It's meant to store cache inside the project folder, but Linux cache can be theoretically shared.
|
||||
ARM compose file has a custom cache folder, so it doesn't conflict with Mac's usual `~/Library/Cache` folder. It's
|
||||
meant to store cache inside the project folder, but Linux cache can be theoretically shared.
|
||||
|
||||
@@ -36,7 +36,7 @@
|
||||
cache: []
|
||||
before_script: []
|
||||
script:
|
||||
- markdownlint-cli2 "*.md" "doc/**/*.md"
|
||||
- markdownlint-cli2 '*.md' '**/*.md' '#node_modules'
|
||||
after_script: []
|
||||
|
||||
'lint: i18n & rails':
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
## Specification
|
||||
# Specification
|
||||
|
||||
<!--Insert the link to a GitHub issue in (), or describe the changes if there is no issue -->
|
||||
[Issue Link]()
|
||||
[Issue Link](/add-your-link-here.tld)
|
||||
|
||||
## Screenshots <!-- Optional, very helpful for the reviewer colleagues from other teams -->
|
||||
## Screenshots <!-- Optional, very helpful for the reviewer colleagues from other teams -->
|
||||
|
||||
### Before
|
||||
|
||||
|
||||
@@ -1,29 +1,52 @@
|
||||
---
|
||||
#
|
||||
# TODO: enable the following rules one by one
|
||||
#
|
||||
|
||||
MD004: false
|
||||
MD012: false
|
||||
MD014: false
|
||||
MD022: false
|
||||
MD024: false
|
||||
MD025: false
|
||||
MD026: false
|
||||
MD029: false
|
||||
MD031: false
|
||||
MD032: false
|
||||
MD040: false
|
||||
MD049: false
|
||||
MD051: false
|
||||
########################################
|
||||
# Remaining difference to zammad-org:
|
||||
# MD033 disabled for zammad-org, but no need to disable it here
|
||||
########################################
|
||||
|
||||
# Default state for all rules
|
||||
default: true
|
||||
|
||||
# MD004/ul-style : Unordered list style : https://github.com/DavidAnson/markdownlint/blob/v0.37.4/doc/md004.md
|
||||
MD004:
|
||||
# List style
|
||||
style: "dash"
|
||||
|
||||
# MD013/line-length : Line length : https://github.com/DavidAnson/markdownlint/blob/v0.37.4/doc/md013.md
|
||||
MD013: false
|
||||
# # Number of characters
|
||||
# line_length: 120
|
||||
# # Exclude code blocks
|
||||
# code_blocks: false
|
||||
# # Exclude tables
|
||||
# tables: false
|
||||
MD013:
|
||||
# Number of characters
|
||||
line_length: 120
|
||||
# Exclude code blocks
|
||||
code_blocks: false
|
||||
# Exclude tables
|
||||
tables: false
|
||||
|
||||
# MD024/no-duplicate-heading : Multiple headings with the same content : https://github.com/DavidAnson/markdownlint/blob/v0.37.4/doc/md024.md
|
||||
MD024:
|
||||
# Only check sibling headings
|
||||
siblings_only: true
|
||||
|
||||
# MD025/single-title/single-h1 : Multiple top-level headings in the same document : https://github.com/DavidAnson/markdownlint/blob/v0.37.4/doc/md025.md
|
||||
MD025:
|
||||
# RegExp for matching title in front matter
|
||||
front_matter_title: false
|
||||
|
||||
# MD046/code-block-style : Code block style : https://github.com/DavidAnson/markdownlint/blob/v0.37.4/doc/md046.md
|
||||
MD046:
|
||||
# Block style
|
||||
style: "fenced"
|
||||
|
||||
# MD048/code-fence-style : Code fence style : https://github.com/DavidAnson/markdownlint/blob/v0.37.4/doc/md048.md
|
||||
MD048:
|
||||
# Code fence style
|
||||
style: "backtick"
|
||||
|
||||
# MD049/emphasis-style : Emphasis style : https://github.com/DavidAnson/markdownlint/blob/v0.37.4/doc/md049.md
|
||||
MD049:
|
||||
# Emphasis style
|
||||
style: "underscore"
|
||||
|
||||
# MD050/strong-style : Strong style : https://github.com/DavidAnson/markdownlint/blob/v0.37.4/doc/md050.md
|
||||
MD050:
|
||||
# Strong style
|
||||
style: "asterisk"
|
||||
|
||||
@@ -86,10 +86,11 @@ PreCommit:
|
||||
required_executable: 'pnpm'
|
||||
enabled: true
|
||||
command: ['pnpm', 'lint:md:cmd']
|
||||
flags: ['*.md', 'doc/**/*.md']
|
||||
flags: ['*.md', '**/*.md', '#node_modules']
|
||||
exclude:
|
||||
- 'node_modules'
|
||||
include:
|
||||
- '*.md'
|
||||
- 'doc/**/*.md'
|
||||
- '**/*.md'
|
||||
|
||||
PostCheckout:
|
||||
ALL:
|
||||
|
||||
@@ -4,17 +4,26 @@
|
||||
|
||||
### Textarea object manager attribute values
|
||||
|
||||
When used as [template variables](https://admin-docs.zammad.org/en/latest/misc/variables.html), the `textarea` object manager attributes are now replaced with an HTML representation of their value. This is a consequence of a bugfix for [#5330](https://github.com/zammad/zammad/issues/5330), which expects newline characters are respected for these attributes in all contexts, including the rich text article body. The administrators are advised to check for usage of such variables in their objects (e.g. triggers, text modules, etc), by making sure the new value type will not break their existing workflows.
|
||||
When used as [template variables](https://admin-docs.zammad.org/en/latest/misc/variables.html), the `textarea` object
|
||||
manager attributes are now replaced with an HTML representation of their value. This is a consequence of a bugfix for
|
||||
[#5330](https://github.com/zammad/zammad/issues/5330), which expects newline characters are respected for these
|
||||
attributes in all contexts, including the rich text article body. The administrators are advised to check for usage of
|
||||
such variables in their objects (e.g. triggers, text modules, etc), by making sure the new value type will not break
|
||||
their existing workflows.
|
||||
|
||||
### Changes to search API endpoints
|
||||
|
||||
All search endpoints (`/:object/search`) have been revised, extended and unified. This will also result in breaking changes in the existing endpoints. Be prepared that the structure in the responses may change (have a look at the [API documentation](https://docs.zammad.org/en/latest/api/intro.html) where you can find updated examples).
|
||||
All search endpoints (`/:object/search`) have been revised, extended and unified. This will also result in breaking
|
||||
changes in the existing endpoints. Be prepared that the structure in the responses may change (have a look at the
|
||||
[API documentation](https://docs.zammad.org/en/latest/api/intro.html) where you can find updated examples).
|
||||
|
||||
The **standard search** (e.g. `/ticket/search`) returned a hash for some objects, such as the ticket. This will no longer be the case.
|
||||
The **standard search** (e.g. `/ticket/search`) returned a hash for some objects, such as the ticket. This will no
|
||||
longer be the case.
|
||||
|
||||
The structure for the **expanded search** (e.g. `/ticket/search?expand=true`) remains the same.
|
||||
|
||||
The structure of the **full search** (e.g. `/ticket/search?full=true`) remains the same, but is supplemented by a `total_count`, which counts all results.
|
||||
The structure of the **full search** (e.g. `/ticket/search?full=true`) remains the same, but is supplemented by a
|
||||
`total_count`, which counts all results.
|
||||
|
||||
Some objects used an object-related hash key, such as `ticket_ids`. This is now always `record_ids`.
|
||||
|
||||
@@ -22,29 +31,39 @@ The **count search** (e.g. `/ticket/search?only_total_count=true`) is a new fea
|
||||
|
||||
### API performance optimization of asset return data
|
||||
|
||||
Most API endpoints have some parameter called full=true which returns the data with all related assets. [In order to improve the front end performance](https://github.com/zammad/zammad/issues/5495), we decided to reduce certain assets which are populated on the login. Normally this parameter is mainly used to show additional data to our legacy app. We have some static data which rarely changes and are currently added on every object like:
|
||||
Most API endpoints have some parameter called full=true which returns the data with all related assets.
|
||||
[In order to improve the front end performance](https://github.com/zammad/zammad/issues/5495), we decided to reduce
|
||||
certain assets which are populated on the login. Normally this parameter is mainly used to show additional data to our
|
||||
legacy app. We have some static data which rarely changes and are currently added on every object like:
|
||||
|
||||
- Ticket Priority
|
||||
- Ticket State
|
||||
- Ticket Group
|
||||
- Role
|
||||
|
||||
This information will not be added in the future any more when requesting a user or a ticket. If you have an external script which is for example requesting tickets with assets and using the group name or some role information out of the assets, you need to adjust your code to do either:
|
||||
This information will not be added in the future any more when requesting a user or a ticket. If you have an external
|
||||
script which is for example requesting tickets with assets and using the group name or some role information out of the
|
||||
assets, you need to adjust your code to do either:
|
||||
|
||||
1. Do a separate request to the object specific endpoint e.g. `/api/v1/groups`
|
||||
2. Get the global assets before requesting the ticket e.g. `/api/v1/signshow`
|
||||
|
||||
### Limit to one `merged` state
|
||||
|
||||
It will not be possible to have more than one state of the `merged` type. Additional states will be changed to the `closed` type automatically with that update. If you want to prevent that, make sure to only have one state of the type `merged` before you make an update to the **next release**.
|
||||
It will not be possible to have more than one state of the `merged` type. Additional states will be changed to the
|
||||
`closed` type automatically with that update. If you want to prevent that, make sure to only have one state of the type
|
||||
`merged` before you make an update to the **next release**.
|
||||
|
||||
### `APP_RESTART_CMD` and Zammad self-shutdown
|
||||
|
||||
Zammad will now cause a self-shutdown of all running processes after certain configuration changes by default. It is the responsibility of the controlling process manager (e.g. Docker, Kubernetes, systemd) to bring them up again by way of a proper restart policy. This is the default for vanilla Docker, Kubernetes or Package deployments of Zammad.
|
||||
Zammad will now cause a self-shutdown of all running processes after certain configuration changes by default. It is the
|
||||
responsibility of the controlling process manager (e.g. Docker, Kubernetes, systemd) to bring them up again by way of a
|
||||
proper restart policy. This is the default for vanilla Docker, Kubernetes or Package deployments of Zammad.
|
||||
|
||||
The previous environment variable `APP_RESTART_CMD` is not supported any more.
|
||||
|
||||
For systems where this behaviour is not wanted, it can be disabled by setting the Zammad Setting `auto_shutdown` to `false`.
|
||||
For systems where this behaviour is not wanted, it can be disabled by setting the Zammad Setting `auto_shutdown` to
|
||||
`false`.
|
||||
|
||||
### `ZAMMAD_SESSION_JOBS_CONCURRENT` was renamed to `ZAMMAD_PROCESS_SESSIONS_JOBS_WORKERS`
|
||||
|
||||
@@ -58,7 +77,8 @@ to work for now, but emit a deprecation warning.
|
||||
|
||||
### nginx configuration update
|
||||
|
||||
Please update your nginx configuration file to insert the line `proxy_set_header Host $http_host;` to the `location /ws` and `location /cable` sections like in the example below:
|
||||
Please update your nginx configuration file to insert the line `proxy_set_header Host $http_host;` to the `location /ws`
|
||||
and `location /cable` sections like in the example below:
|
||||
|
||||
```diff
|
||||
@@ -38,10 +38,11 @@ server {
|
||||
@@ -91,67 +111,100 @@ Please update your nginx configuration file to insert the line `proxy_set_header
|
||||
|
||||
### JavaScript Package Manager Change
|
||||
|
||||
This version changes the JavaScript toolchains to be based on pnpm rather than yarn. This is only relevant for source installations, where you need to provide a recent version of pnpm in order to run the assets:precompile command.
|
||||
This version changes the JavaScript toolchains to be based on pnpm rather than yarn. This is only relevant for source
|
||||
installations, where you need to provide a recent version of pnpm in order to run the assets:precompile command.
|
||||
|
||||
### Changed CSV-format for user/organization import/export
|
||||
|
||||
We slightly changed the format of the CSV-files you use for importing/exporting users and organizations. If you somehow do that in an automated process via our REST-API, you will need to review that process before updating to Zammad 6.4. Check the details in our documentation.
|
||||
We slightly changed the format of the CSV-files you use for importing/exporting users and organizations. If you somehow
|
||||
do that in an automated process via our REST-API, you will need to review that process before updating to Zammad 6.4.
|
||||
Check the details in our documentation.
|
||||
|
||||
## 6.3
|
||||
|
||||
### Knowledge base granular permissions setup changed
|
||||
|
||||
Zammad allows configuration of a granular permission structure for knowledge base access. Previous Zammad versions allowed to misconfigure this in cases of allowing agents editor access to only some, but not all categories: it was possible to grant editor access at a higher level in the category tree, and then restricting access to reader or none for sub-categories. This was not effective due to permission inheritance.
|
||||
Zammad allows configuration of a granular permission structure for knowledge base access. Previous Zammad versions
|
||||
allowed to misconfigure this in cases of allowing agents editor access to only some, but not all categories: it was
|
||||
possible to grant editor access at a higher level in the category tree, and then restricting access to reader or none
|
||||
for sub-categories. This was not effective due to permission inheritance.
|
||||
|
||||
Such a misconfiguration is no longer possible in Zammad 6.3. Administrators with existing knowledge base granular permission structures should review their configuration to ensure that at top-level only reader access is granted, and editor access only for the relevant sub-categories.
|
||||
Such a misconfiguration is no longer possible in Zammad 6.3. Administrators with existing knowledge base granular
|
||||
permission structures should review their configuration to ensure that at top-level only reader access is granted, and
|
||||
editor access only for the relevant sub-categories.
|
||||
|
||||
### Permissions for Ticket State and Priority REST-API
|
||||
|
||||
With this release, we will introduce new permissions for the ticket state and priority management. It will no longer be possible to access the corresponding REST-API with "admin.object" permission. Existing roles and/or access tokens that are used for these specific REST-API endpoints need to be updated to include the new permissions ("admin.ticket_state" and "admin.ticket_priority").
|
||||
With this release, we will introduce new permissions for the ticket state and priority management. It will no longer be
|
||||
possible to access the corresponding REST-API with "admin.object" permission. Existing roles and/or access tokens that
|
||||
are used for these specific REST-API endpoints need to be updated to include the new permissions ("admin.ticket_state"
|
||||
and "admin.ticket_priority").
|
||||
|
||||
## 6.2
|
||||
|
||||
### Default SSL Verification in UserAgent
|
||||
|
||||
The default SSL behaviour of the *UserAgent* class in Zammad was changed. Previously, it would not perform SSL verification unless explicitly requested. Now, it will perform SSL verification unless explicitly rejected.
|
||||
The default SSL behaviour of the _UserAgent_ class in Zammad was changed. Previously, it would not perform SSL
|
||||
verification unless explicitly requested. Now, it will perform SSL verification unless explicitly rejected.
|
||||
|
||||
This may cause issues on systems with custom addons using the *UserAgent* to access other systems via *https*, if these systems have self-signed certificates. In such cases, these certificates or the CA certificates used for their generation should be uploaded via the new *SSL Certificates* management screen of Zammad. Alternatively, custom code can be adjusted to pass *verify_ssl: false* to *UserAgent* calls to restore the old behaviour.
|
||||
This may cause issues on systems with custom addons using the _UserAgent_ to access other systems via _https_, if these
|
||||
systems have self-signed certificates. In such cases, these certificates or the CA certificates used for their
|
||||
generation should be uploaded via the new _SSL Certificates_ management screen of Zammad. Alternatively, custom code can
|
||||
be adjusted to pass _verify_ssl: false_ to _UserAgent_ calls to restore the old behaviour.
|
||||
|
||||
### Oversized Email Handling
|
||||
|
||||
The handling of emails larger than the size limit changed. Previously, Zammad would send a reply and save the emails locally in *var/spool/oversized_email* (if the setting *postmaster_send_reject_if_mail_too_large* is *true*). No ticket is created in this case.
|
||||
The handling of emails larger than the size limit changed. Previously, Zammad would send a reply and save the emails
|
||||
locally in _var/spool/oversized_email_ (if the setting _postmaster_send_reject_if_mail_too_large_ is _true_). No ticket
|
||||
is created in this case.
|
||||
|
||||
The new behaviour is that Zammad sends the reply like before, but no longer creates files for these emails locally - they are discarded.
|
||||
The new behaviour is that Zammad sends the reply like before, but no longer creates files for these emails locally -
|
||||
they are discarded.
|
||||
|
||||
### Reserved Delimiter in Group Name
|
||||
|
||||
The double colon (`::`) is now a reserved delimiter in the group name, in order to facilitate nested structure for complex hierarchies. Previously, it was possible to freely use this set of characters as part of the group name, but now it is forbidden.
|
||||
The double colon (`::`) is now a reserved delimiter in the group name, in order to facilitate nested structure for
|
||||
complex hierarchies. Previously, it was possible to freely use this set of characters as part of the group name, but
|
||||
now it is forbidden.
|
||||
|
||||
On existing systems, the group names that contain the now reserved delimiter will be renamed, with sets of double colons being replaced by a dash (`-`) during the migration process.
|
||||
On existing systems, the group names that contain the now reserved delimiter will be renamed, with sets of double colons
|
||||
being replaced by a dash (`-`) during the migration process.
|
||||
|
||||
Additionally, existing custom group object attributes named *name_last* and *parent_id* will be renamed too, by adding an underscore in front (*_name_last* and *_parent_id*). This is due to these attributes now being part of the group model, requiring dedicated table columns under the reserved names.
|
||||
Additionally, existing custom group object attributes named _name\_last_ and _parent\_id_ will be renamed too, by adding
|
||||
an underscore in front (_\_name\_last_ and _\_parent\_id_). This is due to these attributes now being part of the group
|
||||
model, requiring dedicated table columns under the reserved names.
|
||||
|
||||
### Disallowed URL Values in User's Name Attributes
|
||||
|
||||
Text values that resemble valid URI addresses are now disallowed for user's first and last name attributes. Previously, it was possible to save any text in these attributes. The administrators should take a note of this change since it can have an impact on existing user data.
|
||||
Text values that resemble valid URI addresses are now disallowed for user's first and last name attributes. Previously,
|
||||
it was possible to save any text in these attributes. The administrators should take a note of this change since it can
|
||||
have an impact on existing user data.
|
||||
|
||||
No migration will be run for existing users on update to Zammad 6.2. In case there are user records that contain URLs in their name attributes, they will be sanitized during subsequent updates. No manual action from administrator will be required, as the URI scheme or protocol will be automatically stripped from offending values.
|
||||
No migration will be run for existing users on update to Zammad 6.2. In case there are user records that contain URLs in
|
||||
their name attributes, they will be sanitized during subsequent updates. No manual action from administrator will be
|
||||
required, as the URI scheme or protocol will be automatically stripped from offending values.
|
||||
|
||||
## 6.1
|
||||
|
||||
### New Organization Attribute `vip`
|
||||
|
||||
Zammad 6.1 creates a new `vip` attribute for organizations. For systems with previously created `vip` attributes, there is special caution needed. In case of `boolean` attributes, Zammad will adjust them to the new settings and keep using them. For attributes of other types, Zammad will rename the existing attribute to `_vip` and add a new `vip` boolean attribute. This may cause issues if the previous attribute was used in other parts of the system, e.g. Triggers. In such cases, the relevant configurations must be reviewed and adjusted.
|
||||
Zammad 6.1 creates a new `vip` attribute for organizations. For systems with previously created `vip` attributes, there
|
||||
is special caution needed. In case of `boolean` attributes, Zammad will adjust them to the new settings and keep using
|
||||
them. For attributes of other types, Zammad will rename the existing attribute to `_vip` and add a new `vip` boolean
|
||||
attribute. This may cause issues if the previous attribute was used in other parts of the system, e.g. Triggers.
|
||||
In such cases, the relevant configurations must be reviewed and adjusted.
|
||||
|
||||
### Support for the Unicorn Web Server is removed
|
||||
|
||||
It seems that the Unicorn Web Server is no longer really used with Zammad. Therefore, we have decided to remove it with Zammad 6.1 after it was deprecated in Zammad 6.0.
|
||||
It seems that the Unicorn Web Server is no longer really used with Zammad. Therefore, we have decided to remove it with
|
||||
Zammad 6.1 after it was deprecated in Zammad 6.0.
|
||||
|
||||
## 6.0
|
||||
|
||||
### nginx configuration update
|
||||
|
||||
When updating to Zammad 6.0 from a previous version, the system administrator needs to add some content to the configuration of the reverse proxy.
|
||||
When updating to Zammad 6.0 from a previous version, the system administrator needs to add some content to the
|
||||
configuration of the reverse proxy.
|
||||
|
||||
Example for Apache:
|
||||
|
||||
@@ -174,32 +227,45 @@ location /cable {
|
||||
}
|
||||
```
|
||||
|
||||
This is required to enable the new Rails Action Cable based realtime communication. You can find more details about this change at [this github commit](https://github.com/zammad/zammad/commit/d873b2a04bd172b90573170bc2d1d4ee75a47f02).
|
||||
This is required to enable the new Rails Action Cable based realtime communication. You can find more details about this
|
||||
change at [this github commit](https://github.com/zammad/zammad/commit/d873b2a04bd172b90573170bc2d1d4ee75a47f02).
|
||||
|
||||
### Mandatory Redis Dependency
|
||||
|
||||
Starting with Zammad version 6.0, Redis is required to run Zammad. For package-based installations, the new dependency is automatically installed in the system during the update.
|
||||
Starting with Zammad version 6.0, Redis is required to run Zammad. For package-based installations, the new dependency
|
||||
is automatically installed in the system during the update.
|
||||
|
||||
Note: Hosted customers do not need to take any further action regarding this change!
|
||||
|
||||
### Health Check API Changes
|
||||
|
||||
Starting with Zammad 6.0, the "health check" monitoring API at `/api/v1/monitoring/health_check` will no longer echo the used authentication token in the response payload.
|
||||
Starting with Zammad 6.0, the "health check" monitoring API at `/api/v1/monitoring/health_check` will no longer echo the
|
||||
used authentication token in the response payload.
|
||||
|
||||
### Excel Export Format Change
|
||||
|
||||
Starting with Zammad version 6.0, all Excel exports will be exported exclusively in xlsx format. The original xls format will no longer be supported.
|
||||
Starting with Zammad version 6.0, all Excel exports will be exported exclusively in xlsx format. The original xls format
|
||||
will no longer be supported.
|
||||
|
||||
### Storage location of unprocessable/oversized emails
|
||||
|
||||
Zammad stores emails that were unprocessable or rejected due to size constraints in the file system. The location of such emails changed from `tmp/unprocessable_mail` and `tmp/oversized_mail` to `var/spool/unprocessable_mail` and `var/spool/oversized_mail` within the `/opt/zammad` directory. Existing emails are automatically moved to the new location.
|
||||
Zammad stores emails that were unprocessable or rejected due to size constraints in the file system. The location of
|
||||
such emails changed from `tmp/unprocessable_mail` and `tmp/oversized_mail` to `var/spool/unprocessable_mail` and
|
||||
`var/spool/oversized_mail` within the `/opt/zammad` directory. Existing emails are automatically moved to the new
|
||||
location.
|
||||
|
||||
### Naming change in Token model and EmailAddress model
|
||||
|
||||
The `token` model is used to store access tokens and had field names which may have caused confusion for developers using them. Therefore, the field previously called `name:` now has the correct identifier `token:` (as it stores the actual token value), and the field previously called `label:` is now called `name:` for better consistency with other models. The `EmailAddress` model is used to information about email addresses Zammad receives mail for. For consistency reasons, its `realname:` field is now called `name:`.
|
||||
The `token` model is used to store access tokens and had field names which may have caused confusion for developers
|
||||
using them. Therefore, the field previously called `name:` now has the correct identifier `token:` (as it stores the
|
||||
actual token value), and the field previously called `label:` is now called `name:` for better consistency with other
|
||||
models. The `EmailAddress` model is used to information about email addresses Zammad receives mail for. For consistency
|
||||
reasons, its `realname:` field is now called `name:`.
|
||||
|
||||
This means that the attribute via the REST API also changes: from token or realname to "name".
|
||||
|
||||
### Docker image zammad-docker was archived
|
||||
|
||||
The repository [zammad-docker](https://github.com/zammad/zammad-docker) was intended for testing / development purposes only. This repository was archived and will receive no further updates. Please use [zammad-docker-compose](https://github.com/zammad/zammad-docker-compose) instead.
|
||||
The repository [zammad-docker](https://github.com/zammad/zammad-docker) was intended for testing / development purposes
|
||||
only. This repository was archived and will receive no further updates. Please use
|
||||
[zammad-docker-compose](https://github.com/zammad/zammad-docker-compose) instead.
|
||||
|
||||
@@ -18,23 +18,23 @@ diverse, inclusive, and healthy community.
|
||||
Examples of behavior that contributes to a positive environment for our
|
||||
community include:
|
||||
|
||||
* Demonstrating empathy and kindness toward other people
|
||||
* Being respectful of differing opinions, viewpoints, and experiences
|
||||
* Giving and gracefully accepting constructive feedback
|
||||
* Accepting responsibility and apologizing to those affected by our mistakes,
|
||||
- Demonstrating empathy and kindness toward other people
|
||||
- Being respectful of differing opinions, viewpoints, and experiences
|
||||
- Giving and gracefully accepting constructive feedback
|
||||
- Accepting responsibility and apologizing to those affected by our mistakes,
|
||||
and learning from the experience
|
||||
* Focusing on what is best not just for us as individuals, but for the overall
|
||||
- Focusing on what is best not just for us as individuals, but for the overall
|
||||
community
|
||||
|
||||
Examples of unacceptable behavior include:
|
||||
|
||||
* The use of sexualized language or imagery, and sexual attention or advances of
|
||||
- The use of sexualized language or imagery, and sexual attention or advances of
|
||||
any kind
|
||||
* Trolling, insulting or derogatory comments, and personal or political attacks
|
||||
* Public or private harassment
|
||||
* Publishing others' private information, such as a physical or email address,
|
||||
- Trolling, insulting or derogatory comments, and personal or political attacks
|
||||
- Public or private harassment
|
||||
- Publishing others' private information, such as a physical or email address,
|
||||
without their explicit permission
|
||||
* Other conduct which could reasonably be considered inappropriate in a
|
||||
- Other conduct which could reasonably be considered inappropriate in a
|
||||
professional setting
|
||||
|
||||
## Enforcement Responsibilities
|
||||
|
||||
13
README.md
13
README.md
@@ -28,10 +28,15 @@ has a bright and sustainable future, consider becoming a Zammad customer!
|
||||
|
||||
## Status
|
||||
|
||||
- Toolchain: [](https://github.com/zammad/zammad/actions/workflows/ci.yaml) [](https://github.com/zammad/zammad/actions/workflows/docker-release.yaml) [](https://docs.zammad.org)
|
||||
- Docker container images: [](https://hub.docker.com/r/zammad/zammad-docker-compose) [](https://hub.docker.com/r/zammad/zammad-docker-compose/)
|
||||
- Helm chart for Kubernetes: [](https://artifacthub.io/packages/helm/zammad/zammad) [](https://github.com/zammad/zammad-helm/releases)
|
||||
- Download DEB/RPM: [](https://packager.io/gh/zammad/zammad/refs/stable) [](https://packager.io/gh/zammad/zammad/refs/develop)
|
||||
- Toolchain: [](https://github.com/zammad/zammad/actions/workflows/ci.yaml)
|
||||
[](https://github.com/zammad/zammad/actions/workflows/docker-release.yaml)
|
||||
[](https://docs.zammad.org)
|
||||
- Docker container images: [](https://hub.docker.com/r/zammad/zammad-docker-compose)
|
||||
[](https://hub.docker.com/r/zammad/zammad-docker-compose/)
|
||||
- Helm chart for Kubernetes: [](https://artifacthub.io/packages/helm/zammad/zammad)
|
||||
[](https://github.com/zammad/zammad-helm/releases)
|
||||
- Download DEB/RPM: [](https://packager.io/gh/zammad/zammad/refs/stable)
|
||||
[](https://packager.io/gh/zammad/zammad/refs/develop)
|
||||
- License: [](https://github.com/zammad/zammad/blob/develop/LICENSE)
|
||||
|
||||
## Further Information
|
||||
|
||||
@@ -42,7 +42,9 @@ With this, you can also locally reproduce the results.
|
||||
|
||||
### Dependency Management
|
||||
|
||||
We use renovate bot to keep our Ruby and JS dependencies up-to-date by automatic merge requests in our internal GitLab. This config is not visible in our source code, but you can see frequent commits from it in our history, like [this one](https://github.com/zammad/zammad/commit/a61b205e4ba41fca1ec7c85323ec6045fc3672e5).
|
||||
We use renovate bot to keep our Ruby and JS dependencies up-to-date by automatic merge requests in our internal GitLab.
|
||||
This config is not visible in our source code, but you can see frequent commits from it in our history, like
|
||||
[this one](https://github.com/zammad/zammad/commit/a61b205e4ba41fca1ec7c85323ec6045fc3672e5).
|
||||
|
||||
### Dependency Security Analysis
|
||||
|
||||
|
||||
@@ -96,7 +96,7 @@
|
||||
|
||||
- Author: The Bootstrap Authors
|
||||
- License: MIT
|
||||
- URL: https://github.com/twbs/icons
|
||||
- URL: <https://github.com/twbs/icons>
|
||||
|
||||
- `assets/crown.svg`
|
||||
|
||||
@@ -106,53 +106,53 @@
|
||||
- `assets/github.svg`
|
||||
|
||||
- Author: GitHub
|
||||
- URL: https://github.com/logos
|
||||
- URL: <https://github.com/logos>
|
||||
|
||||
- `assets/gitlab.svg`
|
||||
|
||||
- Author: GitLab
|
||||
- URL: https://about.gitlab.com/press/press-kit/
|
||||
- URL: https://github.com/logos
|
||||
- URL: <https://about.gitlab.com/press/press-kit/>
|
||||
- URL: <https://github.com/logos>
|
||||
|
||||
- `assets/google.svg`
|
||||
|
||||
- Author: Google
|
||||
- URL: https://about.google/brand-resource-center/
|
||||
- URL: <https://about.google/brand-resource-center/>
|
||||
|
||||
- `assets/facebook.svg`
|
||||
|
||||
- Author: Facebook
|
||||
- URL: https://www.facebook.com/brand/resources/facebookapp/logo
|
||||
- URL: <https://www.facebook.com/brand/resources/facebookapp/logo>
|
||||
|
||||
- `assets/linkedin.svg`
|
||||
|
||||
- Author: LinkedIn
|
||||
- URL: https://brand.linkedin.com/downloads
|
||||
- URL: <https://brand.linkedin.com/downloads>
|
||||
|
||||
- `assets/microsoft.svg`
|
||||
|
||||
- Author: Microsoft
|
||||
- URL: https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks
|
||||
- URL: <https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks>
|
||||
|
||||
- `assets/openid-connect.svg`
|
||||
- Author: OpenID
|
||||
- URL: https://openid.net
|
||||
- URL: <https://openid.net>
|
||||
|
||||
- `assets/saml.svg`
|
||||
|
||||
- Author: OASIS
|
||||
- URL: https://saml.xml.org/wiki/saml-logos
|
||||
- URL: <https://saml.xml.org/wiki/saml-logos>
|
||||
|
||||
- `assets/sina-weibo.svg`
|
||||
|
||||
- Author: Sina Weibo
|
||||
- URL: https://weibo.com
|
||||
- URL: <https://weibo.com>
|
||||
|
||||
- `assets/twitter.svg`
|
||||
|
||||
- Author: Twitter
|
||||
- URL: https://about.twitter.com/en/who-we-are/brand-toolkit
|
||||
- URL: <https://about.twitter.com/en/who-we-are/brand-toolkit>
|
||||
|
||||
- `assets/whatsapp.svg`
|
||||
- Author: Meta
|
||||
- URL: https://about.meta.com/uk/brand/resources/whatsapp/whatsapp-brand/
|
||||
- URL: <https://about.meta.com/uk/brand/resources/whatsapp/whatsapp-brand/>
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
- `assets/apple.svg`
|
||||
- Author: Apple
|
||||
- URL: https://www.apple.com/uk/legal/intellectual-property/guidelinesfor3rdparties.html
|
||||
- URL: <https://www.apple.com/uk/legal/intellectual-property/guidelinesfor3rdparties.html>
|
||||
|
||||
- `assets/crown.svg`
|
||||
- Author: Felix Niklas
|
||||
@@ -10,41 +10,41 @@
|
||||
|
||||
- `assets/github.svg`
|
||||
- Author: GitHub
|
||||
- URL: https://github.com/logos
|
||||
- URL: <https://github.com/logos>
|
||||
|
||||
- `assets/gitlab.svg`
|
||||
- Author: GitLab
|
||||
- URL: https://about.gitlab.com/press/press-kit/
|
||||
- URL: https://github.com/logos
|
||||
- URL: <https://about.gitlab.com/press/press-kit/>
|
||||
- URL: <https://github.com/logos>
|
||||
|
||||
- `assets/google.svg`
|
||||
- Author: Google
|
||||
- URL: https://about.google/brand-resource-center/
|
||||
- URL: <https://about.google/brand-resource-center/>
|
||||
|
||||
- `assets/facebook.svg`
|
||||
- Author: Facebook
|
||||
- URL: https://www.facebook.com/brand/resources/facebookapp/logo
|
||||
- URL: <https://www.facebook.com/brand/resources/facebookapp/logo>
|
||||
|
||||
- `assets/microsoft.svg`
|
||||
- Author: Microsoft
|
||||
- URL: https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks
|
||||
- URL: <https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks>
|
||||
|
||||
- `assets/openid-connect.svg`
|
||||
- Author: OpenID
|
||||
- URL: https://openid.net
|
||||
- URL: <https://openid.net>
|
||||
|
||||
- `assets/saml.svg`
|
||||
- Author: OASIS
|
||||
- URL: https://saml.xml.org/wiki/saml-logos
|
||||
- URL: <https://saml.xml.org/wiki/saml-logos>
|
||||
|
||||
- `assets/sina-weibo.svg`
|
||||
- Author: Sina Weibo
|
||||
- URL: https://weibo.com
|
||||
- URL: <https://weibo.com>
|
||||
|
||||
- `assets/twitter.svg`
|
||||
- Author: Twitter
|
||||
- URL: https://about.twitter.com/en/who-we-are/brand-toolkit
|
||||
- URL: <https://about.twitter.com/en/who-we-are/brand-toolkit>
|
||||
|
||||
- `assets/whatsapp.svg`
|
||||
- Author: Meta
|
||||
- URL: https://about.meta.com/uk/brand/resources/whatsapp/whatsapp-brand/
|
||||
- URL: <https://about.meta.com/uk/brand/resources/whatsapp/whatsapp-brand/>
|
||||
|
||||
@@ -1,22 +1,30 @@
|
||||
# Rules for Icons in the New Stack
|
||||
|
||||
- All icon names must be unique, however you are free to put them in another set (subdirectory).
|
||||
- All icons must use fill for their elements, but not stroke. In case of outlined design, please expand the stroke into a path first.
|
||||
- All icons must be provided in a monochrome design and any fill values must be removed from the SVG definition. This includes `fill="none"` on the root element too. An implicit `fill: currentColor` rule is applied by `CommonIcon` component, so it will inherit the color of the surrounding text.
|
||||
- Attributes `fill-rule` and `clip-rule` can be applied only if the design requires it (no implicit attributes are allowed).
|
||||
- All icons must use fill for their elements, but not stroke. In case of outlined design, please expand the stroke into
|
||||
a path first.
|
||||
- All icons must be provided in a monochrome design and any fill values must be removed from the SVG definition. This
|
||||
includes `fill="none"` on the root element too. An implicit `fill: currentColor` rule is applied by `CommonIcon`
|
||||
component, so it will inherit the color of the surrounding text.
|
||||
- Attributes `fill-rule` and `clip-rule` can be applied only if the design requires it (no implicit attributes are
|
||||
allowed).
|
||||
|
||||
## Rules for `desktop` Icon Set
|
||||
|
||||
- All icons must have size of `width="16"` and `height="16"`, any further resizing can happen only inside `CommonIcon` component. Please make sure that `viewBox` is set to `0 0 16 16`.
|
||||
- All icons must have size of `width="16"` and `height="16"`, any further resizing can happen only inside `CommonIcon`
|
||||
component. Please make sure that `viewBox` is set to `0 0 16 16`.
|
||||
- All icons must be put into `app/frontend/apps/desktop/initializer/assets/` directory.
|
||||
- All third-party icons must be credited properly in `app/frontend/apps/desktop/initializer/3RD-PARTY-ICONS.md`.
|
||||
|
||||
## Rules for `mobile` Icon Set
|
||||
|
||||
- All icons must have size of `width="24"` and `height="24"`, any further resizing can happen only inside `CommonIcon` component. Please make sure that `viewBox` is set to `0 0 24 24`.
|
||||
- All icons must have size of `width="24"` and `height="24"`, any further resizing can happen only inside `CommonIcon`
|
||||
component. Please make sure that `viewBox` is set to `0 0 24 24`.
|
||||
- All icons must be put into `app/frontend/apps/mobile/initializer/assets/` directory.
|
||||
- All third-party icons must be credited properly in `app/frontend/apps/mobile/initializer/3RD-PARTY-ICONS.md`.
|
||||
|
||||
# Using Icons in the "shared" Context
|
||||
## Using Icons in the "shared" Context
|
||||
|
||||
All icon names used in shared context should refer to an alias defined in `mobileIconsAliasesMap.ts` and/or `desktopIconsAliasesMap.ts`. Alias refers to the icon name from `assets` folder depending on the app. Alias name is always preferred when displaying an icon even if icon with that name already exists.
|
||||
All icon names used in shared context should refer to an alias defined in `mobileIconsAliasesMap.ts` and/or
|
||||
`desktopIconsAliasesMap.ts`. Alias refers to the icon name from `assets` folder depending on the app. Alias name is
|
||||
always preferred when displaying an icon even if icon with that name already exists.
|
||||
|
||||
@@ -1 +1,3 @@
|
||||
# Mailer
|
||||
|
||||
Please see [this section in the developer manual](../../../doc/developer_manual/standards/how-to-handle-localization.md).
|
||||
@@ -1 +1,3 @@
|
||||
# Messaging
|
||||
|
||||
Please see [this section in the developer manual](../../../doc/developer_manual/standards/how-to-handle-localization.md).
|
||||
@@ -3,9 +3,11 @@
|
||||
This docker image is build from our [stable branch](https://github.com/zammad/zammad/tree/stable).
|
||||
|
||||
It's used in:
|
||||
* https://github.com/zammad/zammad-docker-compose
|
||||
* https://github.com/zammad/zammad-helm
|
||||
|
||||
- <https://github.com/zammad/zammad-docker-compose>
|
||||
- <https://github.com/zammad/zammad-helm>
|
||||
|
||||
## Status
|
||||
|
||||
[](https://github.com/zammad/zammad-docker-compose/actions) [](https://hub.docker.com/r/zammad/zammad-docker-compose/)
|
||||
[](https://github.com/zammad/zammad-docker-compose/actions)
|
||||
[](https://hub.docker.com/r/zammad/zammad-docker-compose/)
|
||||
|
||||
@@ -1,25 +1,23 @@
|
||||
# How to Debug Zammad Processes
|
||||
|
||||
Sometimes it can be helpful to understand the internal state of threads
|
||||
running in a Zammad process. This can be achieved by sending a `SIGWINCH`
|
||||
signal to any Zammad service (railsserver, websocket or background worker)
|
||||
process, which will cause the process to print the state of its threads to
|
||||
STDOUT.
|
||||
Sometimes it can be helpful to understand the internal state of threads running in a Zammad process. This can be
|
||||
achieved by sending a `SIGWINCH` signal to any Zammad service (railsserver, websocket or background worker) process,
|
||||
which will cause the process to print the state of its threads to STDOUT.
|
||||
|
||||
Beware by default this is only available in a production environment. It can be
|
||||
forced by setting the environment variable ENFORCE_THREAD_STATUS_HANDLER to "true".
|
||||
Beware by default this is only available in a production environment. It can be forced by setting the environment
|
||||
variable ENFORCE_THREAD_STATUS_HANDLER to "true".
|
||||
|
||||
- Find out process ID of Zammad webserver
|
||||
|
||||
```screen
|
||||
$ ps
|
||||
PID TTY TIME CMD
|
||||
ps
|
||||
PID TTY TIME CMD
|
||||
…
|
||||
77926 ttys001 0:03.02 puma 6.5.0 (tcp://localhost:3000) [zammad]
|
||||
…
|
||||
```
|
||||
|
||||
- Send the SIGWINCH signal to that process or any of its forked workers. This doesn't acutally "kill" the process.
|
||||
- Send the SIGWINCH signal to that process or any of its forked workers. This doesn't actually "kill" the process.
|
||||
|
||||
```screen
|
||||
kill -SIGWINCH 77926
|
||||
|
||||
@@ -1,16 +1,19 @@
|
||||
# How to Diagnose Email Bugs
|
||||
|
||||
Incoming email is a common source of bugs in Zammad — there's simply no way to anticipate all the different kinds of input the application will receive from the real world.
|
||||
Getting a copy of a raw email will allow you to manually inspect header fields, check possible text encodings, or simply import the email into your own local development instance.
|
||||
Incoming email is a common source of bugs in Zammad — there's simply no way to anticipate all the different kinds of
|
||||
input the application will receive from the real world. Getting a copy of a raw email will allow you to manually
|
||||
inspect header fields, check possible text encodings, or simply import the email into your own local development
|
||||
instance.
|
||||
|
||||
You can ask the bug reporter to run the following command on their machine, and then send you the resulting file. (Obviously, replace `<TICKET_NUMBER>` with the appropriate value.)
|
||||
You can ask the bug reporter to run the following command on their machine, and then send you the resulting file.
|
||||
(Obviously, replace `<TICKET_NUMBER>` with the appropriate value.)
|
||||
|
||||
```sh
|
||||
$ zammad rails r "puts Ticket.find_by(number: '<TICKET_NUMBER>').articles.last.as_raw.content" > /tmp/bug_report_email.eml
|
||||
zammad rails r "puts Ticket.find_by(number: '<TICKET_NUMBER>').articles.last.as_raw.content" > /tmp/bug_report_email.eml
|
||||
```
|
||||
|
||||
Then, you can import it into your own development instance via:
|
||||
|
||||
```sh
|
||||
$ cat /path/to/file.eml | rails r 'Channel::Driver::MailStdin.new'
|
||||
cat /path/to/file.eml | rails r 'Channel::Driver::MailStdin.new'
|
||||
```
|
||||
|
||||
@@ -1,12 +1,15 @@
|
||||
# How to Setup PGP Integration
|
||||
|
||||
For development purposes, it's possible to set up PGP integration for a local Zammad instance. However, since the approach uses self-generated test keys, this is considered unsafe for production. You've been warned!
|
||||
For development purposes, it's possible to set up PGP integration for a local Zammad instance. However, since the
|
||||
approach uses self-generated test keys, this is considered unsafe for production. You've been warned!
|
||||
|
||||
## Configure PGP Integration
|
||||
|
||||
Navigate to the **System > Integrations > PGP** section in GUI, and turn on the toggle switch on top to activate the feature.
|
||||
Navigate to the **System > Integrations > PGP** section in GUI, and turn on the toggle switch on top to activate the
|
||||
feature.
|
||||
|
||||
**Note**: In case your local `gpg` binary cannot be found or it's a wrong version, you may receive an error message on top. Please try to fix it before proceeding by either installing or updating your GnuPG installation.
|
||||
**Note**: In case your local `gpg` binary cannot be found or it's a wrong version, you may receive an error message on
|
||||
top. Please try to fix it before proceeding by either installing or updating your GnuPG installation.
|
||||
|
||||
### Upload Sender Private Key
|
||||
|
||||
@@ -72,10 +75,11 @@ Navigate to the **System > Integrations > PGP** section in GUI, and turn on the
|
||||
-----END PGP PRIVATE KEY BLOCK-----
|
||||
```
|
||||
|
||||
3. Enter *zammad* in **Passphrase** box.
|
||||
3. Enter _zammad_ in **Passphrase** box.
|
||||
4. Click on the **Add** button.
|
||||
|
||||
The test sender private key above was generated for the following sender email address: `zammad@localhost`. In case your sender address is different, please see below on how to re-generate it.
|
||||
The test sender private key above was generated for the following sender email address: `zammad@localhost`. In case
|
||||
your sender address is different, please see below on how to re-generate it.
|
||||
|
||||
### Upload Recipient Public Key
|
||||
|
||||
@@ -117,7 +121,8 @@ The test sender private key above was generated for the following sender email a
|
||||
3. Leave **Passphrase** box empty.
|
||||
4. Click on the **Add** button.
|
||||
|
||||
The test recipient public key above was generated for the following customer email address: `nicole.braun@zammad.org`. In case your recipient address is different, please see below how to re-generate it.
|
||||
The test recipient public key above was generated for the following customer email address: `nicole.braun@zammad.org`.
|
||||
In case your recipient address is different, please see below how to re-generate it.
|
||||
|
||||
## Create a Test Email Ticket with Encrypted & Signed Content
|
||||
|
||||
@@ -126,7 +131,7 @@ The test recipient public key above was generated for the following customer ema
|
||||
3. Provide a **Title**.
|
||||
4. Choose a **Customer** called _Nicole Braun_.
|
||||
5. Provide some **Text**.
|
||||
6. Choose *Users* for the **Group**.
|
||||
6. Choose _Users_ for the **Group**.
|
||||
7. Verify that both **Encrypt** and **Sign** toggle buttons are now active.
|
||||
8. Click on the **Create** button.
|
||||
9. Verify that the first article has a **Security** attribute in article metadata with _PGP: Encrypted / Signed_ value.
|
||||
@@ -144,7 +149,8 @@ You will need a recent installation of `gpg` utility (GnuPG) for the following c
|
||||
export GNUPGHOME
|
||||
```
|
||||
|
||||
On systems with GnuPG version higher than 2.3.0, please set the following configuration option before generating new keys, so they can be backwards compatible:
|
||||
On systems with GnuPG version higher than 2.3.0, please set the following configuration option before generating new
|
||||
keys, so they can be backwards compatible:
|
||||
|
||||
```sh
|
||||
echo "default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed" > "$GNUPGHOME/gpg.conf"
|
||||
@@ -156,7 +162,8 @@ You will need a recent installation of `gpg` utility (GnuPG) for the following c
|
||||
gpg --quick-generate-key "zammad@localhost" rsa4096 sign,encr 10y
|
||||
```
|
||||
|
||||
Where `zammad@localhost` is the key UID, `rsa4096` key algorithm, `sign,encr` key usage and `10y` key expiration date relative to current time.
|
||||
Where `zammad@localhost` is the key UID, `rsa4096` key algorithm, `sign,encr` key usage and `10y` key expiration date
|
||||
relative to current time.
|
||||
|
||||
Provide the key passphrase when asked, confirm it and remember it for later.
|
||||
|
||||
@@ -177,7 +184,10 @@ You will need a recent installation of `gpg` utility (GnuPG) for the following c
|
||||
unset GNUPGHOME
|
||||
```
|
||||
|
||||
You can now upload your new test sender private key. Either upload the actual text file (`zammad@localhost.asc`) or paste its contents in the appropriate box. Remember that the private key export includes the public key information as well, there is no need to import them separately. Also, you will have to provide the passphrase for the private key during the upload to Zammad.
|
||||
You can now upload your new test sender private key. Either upload the actual text file (`zammad@localhost.asc`) or
|
||||
paste its contents in the appropriate box. Remember that the private key export includes the public key information
|
||||
as well, there is no need to import them separately. Also, you will have to provide the passphrase for the private key
|
||||
during the upload to Zammad.
|
||||
|
||||
### Generate Recipient Key
|
||||
|
||||
@@ -188,7 +198,8 @@ You can now upload your new test sender private key. Either upload the actual te
|
||||
export GNUPGHOME
|
||||
```
|
||||
|
||||
On systems with GnuPG version higher than 2.3.0, please set the following configuration option before generating new keys, so they can be backwards compatible:
|
||||
On systems with GnuPG version higher than 2.3.0, please set the following configuration option before generating new
|
||||
keys, so they can be backwards compatible:
|
||||
|
||||
```sh
|
||||
echo "default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed" > "$GNUPGHOME/gpg.conf"
|
||||
@@ -200,7 +211,8 @@ You can now upload your new test sender private key. Either upload the actual te
|
||||
gpg --quick-generate-key "Nicole Braun <nicole.braun@zammad.org>" rsa4096 sign,encr 10y
|
||||
```
|
||||
|
||||
Where `Nicole Braun <nicole.braun@zammad.org>` is the key UID, `rsa4096` key algorithm, `sign,encr` key usage and `10y` key expiration date relative to current time.
|
||||
Where `Nicole Braun <nicole.braun@zammad.org>` is the key UID, `rsa4096` key algorithm, `sign,encr` key usage and
|
||||
`10y` key expiration date relative to current time.
|
||||
|
||||
Provide the key passphrase when asked and confirm it.
|
||||
|
||||
@@ -210,7 +222,8 @@ You can now upload your new test sender private key. Either upload the actual te
|
||||
gpg --output "nicole.braun@zammad.org.pub.asc" --armor --export "Nicole Braun <nicole.braun@zammad.org>"
|
||||
```
|
||||
|
||||
Where `nicole.braun@zammad.org.pub.asc` is the file output for the public key and `Nicole Braun <nicole.braun@zammad.org>` the key UID.
|
||||
Where `nicole.braun@zammad.org.pub.asc` is the file output for the public key and
|
||||
`Nicole Braun <nicole.braun@zammad.org>` the key UID.
|
||||
|
||||
4. Clean up the temporary GPG keyring:
|
||||
|
||||
@@ -219,7 +232,9 @@ You can now upload your new test sender private key. Either upload the actual te
|
||||
unset GNUPGHOME
|
||||
```
|
||||
|
||||
You can now upload your new test recipient public key. Either upload the actual text file (`nicole.braun@zammad.org.pub.asc`) or paste its content in the appropriate box. Note that in this case you should NOT upload the generated private key since the public key may be used only for encryption.
|
||||
You can now upload your new test recipient public key. Either upload the actual text file
|
||||
(`nicole.braun@zammad.org.pub.asc`) or paste its content in the appropriate box. Note that in this case you should NOT
|
||||
upload the generated private key since the public key may be used only for encryption.
|
||||
|
||||
## Other Useful GnuPG commands
|
||||
|
||||
|
||||
@@ -1,10 +1,12 @@
|
||||
# How to Setup S/MIME Integration
|
||||
|
||||
For development purposes, it's possible to set up S/MIME integration for a local Zammad instance. However, since the approach uses self-generated test certificates, this is considered unsafe for production. You've been warned!
|
||||
For development purposes, it's possible to set up S/MIME integration for a local Zammad instance. However, since the
|
||||
approach uses self-generated test certificates, this is considered unsafe for production. You've been warned!
|
||||
|
||||
## Configure S/MIME Integration
|
||||
|
||||
Navigate to the **System > Integrations > S/MIME** section in GUI, and turn on the toggle switch on top to activate the feature.
|
||||
Navigate to the **System > Integrations > S/MIME** section in GUI, and turn on the toggle switch on top to activate the
|
||||
feature.
|
||||
|
||||
### Upload Sender Certificate & Private Key
|
||||
|
||||
@@ -80,7 +82,8 @@ Navigate to the **System > Integrations > S/MIME** section in GUI, and turn on t
|
||||
6. Leave **Enter Private Key Secret** box empty.
|
||||
7. Click on the **Add** button.
|
||||
|
||||
The test sender certificate above was generated for the following sender email address: `zammad@localhost`. In case your sender address is different, please see below how to re-generate it.
|
||||
The test sender certificate above was generated for the following sender email address: `zammad@localhost`. In case
|
||||
your sender address is different, please see below how to re-generate it.
|
||||
|
||||
### Upload Recipient Certificate
|
||||
|
||||
@@ -120,7 +123,8 @@ The test sender certificate above was generated for the following sender email a
|
||||
|
||||
3. Click on the **Add** button.
|
||||
|
||||
The test recipient certificate above was generated for the following customer email address: `nicole.braun@zammad.org`. In case your recipient address is different, please see below how to re-generate it.
|
||||
The test recipient certificate above was generated for the following customer email address: `nicole.braun@zammad.org`.
|
||||
In case your recipient address is different, please see below how to re-generate it.
|
||||
|
||||
### Upload CA Certificate
|
||||
|
||||
@@ -212,7 +216,9 @@ You will need an installation of a recent `openssl` utility for the following co
|
||||
|
||||
Confirm each field with a return (the value will be pre-populated from the configuration file).
|
||||
|
||||
You can now upload your new test CA certificate. Either upload the actual text file (`ca.crt`) or paste its content in appropriate box. Note that in this case you should NOT upload the generated private key since the certificate may be used only for the trust chain verification.
|
||||
You can now upload your new test CA certificate. Either upload the actual text file (`ca.crt`) or paste its content in
|
||||
appropriate box. Note that in this case you should NOT upload the generated private key since the certificate may be
|
||||
used only for the trust chain verification.
|
||||
|
||||
### Generate Sender Certificate & Private Key
|
||||
|
||||
@@ -253,7 +259,8 @@ You can now upload your new test CA certificate. Either upload the actual text f
|
||||
extendedKeyUsage = emailProtection
|
||||
```
|
||||
|
||||
Adjust all `*_default` values to match desired settings. The most important is `emailAddress_default` which must match your sender's email address.
|
||||
Adjust all `*_default` values to match desired settings. The most important is `emailAddress_default` which must
|
||||
match your sender's email address.
|
||||
|
||||
3. Run the following command in the same directory to generate the certificate request:
|
||||
|
||||
@@ -281,7 +288,10 @@ You can now upload your new test CA certificate. Either upload the actual text f
|
||||
openssl x509 -req -days 3650 -in sender.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out sender.crt -addtrust emailProtection -addreject clientAuth -addreject serverAuth -trustout -extensions v3_ca -extfile v3_ca.conf
|
||||
```
|
||||
|
||||
You can now upload your new test sender certificate & private key. Either upload the actual text files (`sender.crt` and `sender.key`) or paste their contents in appropriate boxes. Remember to omit the input for the private key secret since it was not defined during the re-generation, but don't skip the private key upload since the certificate may be used for signing and decryption.
|
||||
You can now upload your new test sender certificate & private key. Either upload the actual text files (`sender.crt`
|
||||
and `sender.key`) or paste their contents in appropriate boxes. Remember to omit the input for the private key secret
|
||||
since it was not defined during the re-generation, but don't skip the private key upload since the certificate may be
|
||||
used for signing and decryption.
|
||||
|
||||
### Generate Recipient Certificate & Private Key
|
||||
|
||||
@@ -321,7 +331,8 @@ You can now upload your new test sender certificate & private key. Either upload
|
||||
extendedKeyUsage = emailProtection
|
||||
```
|
||||
|
||||
Adjust all `*_default` values to match desired settings. The most important is `emailAddress_default` which must match your recipient's email address.
|
||||
Adjust all `*_default` values to match desired settings. The most important is `emailAddress_default` which must
|
||||
match your recipient's email address.
|
||||
|
||||
3. Run the following command in the same directory to generate the certificate request:
|
||||
|
||||
@@ -349,7 +360,9 @@ You can now upload your new test sender certificate & private key. Either upload
|
||||
openssl x509 -req -days 3650 -in recipient.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out recipient.crt -addtrust emailProtection -addreject clientAuth -addreject serverAuth -trustout -extensions v3_ca -extfile v3_ca.conf
|
||||
```
|
||||
|
||||
You can now upload your new test recipient certificate. Either upload the actual text file (`recipient.crt`) or paste its content in appropriate box. Note that in this case you should NOT upload the generated private key since the certificate may be used only for encryption.
|
||||
You can now upload your new test recipient certificate. Either upload the actual text file (`recipient.crt`) or paste
|
||||
its content in appropriate box. Note that in this case you should NOT upload the generated private key since the
|
||||
certificate may be used only for encryption.
|
||||
|
||||
## Other Useful OpenSSL commands
|
||||
|
||||
|
||||
@@ -1,29 +1,35 @@
|
||||
# How to test the development version of Zammad via Docker
|
||||
|
||||
Docker is a container-based software framework for automating deployment of applications.
|
||||
Our Docker image is a **single container** based application designed to have Zammad **up and running fast for testing purposes**.
|
||||
Our Docker image is a **single container** based application designed to have Zammad **up and running fast for testing
|
||||
purposes**.
|
||||
|
||||
Please note that this is a non persistent storage container and **all Zammad data is lost** when you're stopping the container.
|
||||
Please note that this is a non persistent storage container and **all Zammad data is lost** when you're stopping the
|
||||
container.
|
||||
|
||||
## Requirements
|
||||
|
||||
* Docker environment needs to be up and running
|
||||
* at least 4 GB of RAM to run the container
|
||||
- Docker environment needs to be up and running
|
||||
- at least 4 GB of RAM to run the container
|
||||
|
||||
## Docker container
|
||||
|
||||
Docker `run` will run a command in a new container, `-i` attaches stdin and stdout, `-t` allocates a tty.
|
||||
|
||||
1. Run the container
|
||||
### Step 1
|
||||
|
||||
Run the container:
|
||||
|
||||
```sh
|
||||
$ docker container run -ti --rm --name zammad -p 80:80 zammad/zammad
|
||||
docker container run -ti --rm --name zammad -p 80:80 zammad/zammad
|
||||
```
|
||||
|
||||
2. Set `vm.max_map_count` for Elasticsearch
|
||||
### Step 2
|
||||
|
||||
Set `vm.max_map_count` for Elasticsearch:
|
||||
|
||||
```sh
|
||||
$ sysctl -w vm.max_map_count=262144
|
||||
sysctl -w vm.max_map_count=262144
|
||||
```
|
||||
|
||||
> **_Tip for Mac OS:_** [zammad/zammad-docker/issues/27](https://github.com/zammad/zammad-docker/issues/27#issuecomment-455171752)
|
||||
@@ -34,8 +40,8 @@ That's it! You're now using a bash shell inside of a Zammad docker container usi
|
||||
|
||||
To disconnect or detach from the shell without exiting, use the escape sequence `Ctrl-p` + `Ctrl-q`.
|
||||
|
||||
|
||||
### Open Zammad
|
||||
|
||||
Go to [http://localhost](http://localhost) and you'll see:
|
||||
* "Welcome to Zammad!", there you need to create your admin user.
|
||||
|
||||
- "Welcome to Zammad!", there you need to create your admin user.
|
||||
|
||||
@@ -10,22 +10,23 @@ This page explains some Zammad specific extensions that make testing easier.
|
||||
To run tests locally in the test environment, you need to first ensure the `test` database is in the expected state:
|
||||
|
||||
```sh
|
||||
$ RAILS_ENV=test bundle exec rake db:drop db:create zammad:ci:test:prepare
|
||||
RAILS_ENV=test bundle exec rake db:drop db:create zammad:ci:test:prepare
|
||||
```
|
||||
|
||||
Now, running a single test can be done via the following command:
|
||||
|
||||
```sh
|
||||
$ bundle exec rspec spec/system/ticket/zoom_spec.rb
|
||||
bundle exec rspec spec/system/ticket/zoom_spec.rb
|
||||
```
|
||||
|
||||
Note that it's also possible to run a specific test case by including the line number in the command:
|
||||
|
||||
```sh
|
||||
$ bundle exec rspec spec/system/ticket/zoom_spec.rb:1072
|
||||
bundle exec rspec spec/system/ticket/zoom_spec.rb:1072
|
||||
```
|
||||
|
||||
If you would like to specify the used browser for Capybara end-to-end tests, simply set the `BROWSER` environment variable:
|
||||
If you would like to specify the used browser for Capybara end-to-end tests, simply set the `BROWSER` environment
|
||||
variable:
|
||||
|
||||
```sh
|
||||
BROWSER=firefox bundle exec rspec spec/system/ticket/zoom_spec.rb
|
||||
@@ -34,7 +35,7 @@ BROWSER=firefox bundle exec rspec spec/system/ticket/zoom_spec.rb
|
||||
Also running failed tests only is possible with the option `--only-failures`.
|
||||
|
||||
```sh
|
||||
$ bundle exec rspec --only-failures spec/system/ticket/zoom_spec.rb
|
||||
bundle exec rspec --only-failures spec/system/ticket/zoom_spec.rb
|
||||
```
|
||||
|
||||
## Default RSpec Environment
|
||||
@@ -53,28 +54,36 @@ Manages logging in.
|
||||
|
||||
Example usage: `Rspec.describe :example, authenticated_as: true`
|
||||
|
||||
Takes boolean, symbol or lambda. Symbol is a method name to be executed. Works for RSpec's `let` too! Lambda or referenced method are expected to return `User` object or a boolean.
|
||||
Takes boolean, symbol or lambda. Symbol is a method name to be executed. Works for RSpec's `let` too! Lambda or
|
||||
referenced method are expected to return `User` object or a boolean.
|
||||
|
||||
`true` is the default value. It logs in with `admin@example.com` admin user. If a `User` is returned, it attempts to login with it. `false` causes to skip logging in altogether.
|
||||
`true` is the default value. It logs in with `admin@example.com` admin user. If a `User` is returned, it attempts to
|
||||
login with it. `false` causes to skip logging in altogether.
|
||||
|
||||
Lambda or referenced method is evaluated before web page is loaded. Thus this is a good place to prepare for the test. For example to set `Setting`.
|
||||
Lambda or referenced method is evaluated before web page is loaded. Thus this is a good place to prepare for the test.
|
||||
For example to set `Setting`.
|
||||
|
||||
### `time_zone`
|
||||
|
||||
Allows to set custom time zone. Takes Rails timezone names. Beware that it sets timezone for the server process. Browser in CI is not affected.
|
||||
Allows to set custom time zone. Takes Rails timezone names. Beware that it sets timezone for the server process.
|
||||
Browser in CI is not affected.
|
||||
|
||||
Example usage: `Rspec.describe :example, time_zone: 'Vilnius/Lithuania'`
|
||||
|
||||
### `db_strategy: :reset / :reset_all`
|
||||
|
||||
RSpec resets database using transaction after each example. But DBs can't handle some changes (e.g. altering schema) this way. MySQL is especially bad at this.
|
||||
RSpec resets database using transaction after each example. But DBs can't handle some changes (e.g. altering schema)
|
||||
this way. MySQL is especially bad at this.
|
||||
|
||||
- `db_strategy: :reset` will reset database after each example
|
||||
- `db_strategy: :reset_all` will reset database only once after whole context! This is a great way to increase performance. But easy to shoot yourself in a foot too! Use custom `before :all` and `after :all` to setup and tear down environment
|
||||
- `db_strategy: :reset_all` will reset database only once after whole context! This is a great way to increase
|
||||
performance. But easy to shoot yourself in a foot too! Use custom `before :all` and `after :all` to setup and tear down
|
||||
environment
|
||||
|
||||
### `performs_jobs`
|
||||
|
||||
ActiveJob background jobs are not performed automatically outside of `spec/jobs`! If you want to run `performs_jobs` in other Specs, please do following:
|
||||
ActiveJob background jobs are not performed automatically outside of `spec/jobs`! If you want to run `performs_jobs` in
|
||||
other Specs, please do following:
|
||||
|
||||
```ruby
|
||||
context 'example', performs_jobs: true
|
||||
@@ -82,7 +91,8 @@ context 'example', performs_jobs: true
|
||||
|
||||
### `required_envs`
|
||||
|
||||
Checks if required ENVs are present. Raises error if one of them is missing. Since most ENV variables are credentials for 3rd party services, given variables are filtered from VCR cassettes too.
|
||||
Checks if required ENVs are present. Raises error if one of them is missing. Since most ENV variables are credentials
|
||||
for 3rd party services, given variables are filtered from VCR cassettes too.
|
||||
|
||||
```ruby
|
||||
context 'example', required_envs: %w[FACEBOOK_ADMIN_USER_ID FACEBOOK_ADMIN_FIRSTNAME]
|
||||
@@ -92,7 +102,8 @@ context 'example', required_envs: %w[FACEBOOK_ADMIN_USER_ID FACEBOOK_ADMIN_FIRST
|
||||
|
||||
### `await_empty_ajax_queue`
|
||||
|
||||
Forces test to wait for JQuery ajax requests to finish. After the last request is finished, it waits for another 0.5s. Effectively giving time for response to render. Great to use in `TicketZoom` and other complicated views.
|
||||
Forces test to wait for JQuery ajax requests to finish. After the last request is finished, it waits for another 0.5s.
|
||||
Effectively giving time for response to render. Great to use in `TicketZoom` and other complicated views.
|
||||
|
||||
Even if nothing is being loaded, it causes 0.5s pause!
|
||||
|
||||
@@ -108,7 +119,8 @@ end
|
||||
|
||||
### `ensure_websocket`
|
||||
|
||||
Waits till connection to websocket is established. Sometimes actions rely on Websocket. But Capybara may be too fast and execution action before Websocket is established
|
||||
Waits till connection to websocket is established. Sometimes actions rely on Websocket. But Capybara may be too fast
|
||||
and execution action before Websocket is established
|
||||
|
||||
```ruby
|
||||
it 'example' do
|
||||
@@ -147,7 +159,8 @@ it 'example' do
|
||||
end
|
||||
```
|
||||
|
||||
When `expect` is called in the given block, `in_modal` does not wait for modal to close. It assumes the intention was to test something in the modal and closing it is not relevant.
|
||||
When `expect` is called in the given block, `in_modal` does not wait for modal to close. It assumes the intention was
|
||||
to test something in the modal and closing it is not relevant.
|
||||
|
||||
### `wait`
|
||||
|
||||
@@ -157,7 +170,8 @@ Wait for block to return expected value. Supports `#until`, `#until_appears`, `#
|
||||
|
||||
### `have_* / have_no_*`
|
||||
|
||||
Capybara selectors wait for few seconds to see if expectation is fulfilled or not. Thus `expect(page).to have_no_selector()` is much much faster than `expect(page).not_to have_selector()`
|
||||
Capybara selectors wait for few seconds to see if expectation is fulfilled or not. Thus
|
||||
`expect(page).to have_no_selector()` is much much faster than `expect(page).not_to have_selector()`
|
||||
|
||||
### `active_content`
|
||||
|
||||
@@ -183,7 +197,8 @@ Example usage: `find :active_ticket_article, 123`
|
||||
|
||||
#### Finding fields
|
||||
|
||||
FormKit-based fields have a custom implementation, so a number of helpers is provided to make it easier to find them via their labels:
|
||||
FormKit-based fields have a custom implementation, so a number of helpers is provided to make it easier to find them
|
||||
via their labels:
|
||||
|
||||
```ruby
|
||||
find_input('Title')
|
||||
@@ -235,7 +250,8 @@ find_toggle('Boolean').toggle_on
|
||||
find_toggle('Boolean').toggle_off
|
||||
```
|
||||
|
||||
To wait for a custom GraphQL response in autocomplete fields, you can provide expected `gql_filename` and/or `gql_number` arguments:
|
||||
To wait for a custom GraphQL response in autocomplete fields, you can provide expected `gql_filename` and/or
|
||||
`gql_number` arguments:
|
||||
|
||||
```ruby
|
||||
find_autocomplete('Custom').search_for_option('foo', gql_filename: 'shared/entities/user/graphql/queries/user.graphql', gql_number: 4)
|
||||
@@ -270,7 +286,9 @@ within_form(form_updater_gql_number: 2) do
|
||||
end
|
||||
```
|
||||
|
||||
Within the same context all form updater responses (Core Workflow) are automatically tracked and waited on, as well as multiple types of GraphQL responses behind the autocomplete fields. To define a custom starting form updater response number, use the `form_updater_gql_number` argument.
|
||||
Within the same context all form updater responses (Core Workflow) are automatically tracked and waited on, as well as
|
||||
multiple types of GraphQL responses behind the autocomplete fields. To define a custom starting form updater response
|
||||
number, use the `form_updater_gql_number` argument.
|
||||
|
||||
### Custom matchers
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# How to Test With Vitest and Cypress
|
||||
|
||||
The frontend tests are implemented in Vitest.
|
||||
For the Vue.js 3 component tests we use the "Testing Library", which is a offset of the Vue test utils suite.
|
||||
For the Vue.js 3 component tests we use the "Testing Library", which is an offset of the Vue test utils suite.
|
||||
|
||||
As an addition to the normal unit tests and component tests, we have a suite for frontend integration tests.
|
||||
|
||||
@@ -26,15 +26,22 @@ First, the Cypress dependencies needs to be installed: `pnpm cypress:install`.
|
||||
|
||||
Then you can run `pnpm test:ct`, which opens an UI in the selected browser. Here the different tests can be executed.
|
||||
|
||||
> NOTE: Do not try to run snapshot tests in your development environment or with Cypress GUI, since the snapshots will most likely differ from the ones made in CI (see below).
|
||||
> NOTE: Do not try to run snapshot tests in your development environment or with Cypress GUI, since the snapshots will
|
||||
> most likely differ from the ones made in CI (see below).
|
||||
|
||||
#### Snapshots
|
||||
|
||||
All visual regression tests end with `-visual.cy.ts` in their filename. They work by creating a screenshot of an element. Usually, all correct screenshots are already stored inside a git repository. Cypress then compares two screenshots - if they differ, the test will fail.
|
||||
All visual regression tests end with `-visual.cy.ts` in their filename. They work by creating a screenshot of an
|
||||
element. Usually, all correct screenshots are already stored inside a git repository. Cypress then compares two
|
||||
screenshots - if they differ, the test will fail.
|
||||
|
||||
To run the snapshot tests use `CYPRESS_UPDATE_SNAPSHOTS=false pnpm cypress:snapshots` command. This will run all snapshot tests inside a Docker container to ensure they are running in the same environment in CI and on local machine. Before running command, make sure you have `docker` and `docker-compose` installed.
|
||||
To run the snapshot tests use `CYPRESS_UPDATE_SNAPSHOTS=false pnpm cypress:snapshots` command. This will run all
|
||||
snapshot tests inside a Docker container to ensure they are running in the same environment in CI and on local machine.
|
||||
Before running command, make sure you have `docker` and `docker-compose` installed.
|
||||
|
||||
To update snapshots, use `pnpm cypress:snapshots` command. This will run all snapshot tests inside the same inside docker container, but this time it will update and overwrite stored screenshots (the tests will never fail). All that is needed afterwards is to stage and commit updated screenshot files.
|
||||
To update snapshots, use `pnpm cypress:snapshots` command. This will run all snapshot tests inside the same inside
|
||||
docker container, but this time it will update and overwrite stored screenshots (the tests will never fail). All that
|
||||
is needed afterwards is to stage and commit updated screenshot files.
|
||||
|
||||
## Tooling
|
||||
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
# How to Use Debuggers With Zammad
|
||||
|
||||
There is not much explanation needed on how to code. But there always comes the time where you get stuck. We made pretty good experience with the following tools in such situations:
|
||||
There is not much explanation needed on how to code. But there always comes the time where you get stuck. We made
|
||||
pretty good experience with the following tools in such situations:
|
||||
|
||||
- `pry`
|
||||
- `pry-remote`
|
||||
@@ -9,6 +10,9 @@ There is not much explanation needed on how to code. But there always comes the
|
||||
|
||||
## `forego` + debuggers = 🤦
|
||||
|
||||
If you’re used to inserting debugging breakpoints into your code (_e.g.,_ with Pry or Byebug), `forego` may throw you for a loop — since it manages the output of multiple processes, [**your debugger prompt will appear briefly on the screen and then fly past it, along with the STDOUT of any other processes `forego` is overseeing**](https://github.com/ddollar/foreman/issues/58).
|
||||
If you're used to inserting debugging breakpoints into your code (_e.g.,_ with Pry or Byebug), `forego` may throw you
|
||||
for a loop — since it manages the output of multiple processes,
|
||||
[**your debugger prompt will appear briefly on the screen and then fly past it, along with the STDOUT of any other
|
||||
processes `forego` is overseeing**](https://github.com/ddollar/foreman/issues/58).
|
||||
|
||||
Instead, use a remote debugger like [pry-remote](https://github.com/mon-ouie/pry-remote).
|
||||
|
||||
@@ -8,31 +8,31 @@ The Zammad [repository](https://github.com/zammad/zammad) has several branches.
|
||||
|
||||
### `develop`
|
||||
|
||||
* Default GitHub branch
|
||||
* Current unreleased development state of next major release
|
||||
* Is the first instance where all features are being developed
|
||||
* This branch will have open issues
|
||||
* If current stable version is 1.1.0 this will become 1.2.0
|
||||
* Unstable! Should not be used in production environment!
|
||||
* Supported with minor- and security bug fixes.
|
||||
- Default GitHub branch
|
||||
- Current unreleased development state of next major release
|
||||
- Is the first instance where all features are being developed
|
||||
- This branch will have open issues
|
||||
- If current stable version is 1.1.0 this will become 1.2.0
|
||||
- Unstable! Should not be used in production environment!
|
||||
- Supported with minor- and security bug fixes.
|
||||
|
||||
### `stable`
|
||||
|
||||
* Current stable release
|
||||
* Can be used for production
|
||||
* Stable bug fixes will be merged from develop after evaluation of the developers
|
||||
* Supported with minor- and security bug fixes.
|
||||
- Current stable release
|
||||
- Can be used for production
|
||||
- Stable bug fixes will be merged from develop after evaluation of the developers
|
||||
- Supported with minor- and security bug fixes.
|
||||
|
||||
### `stable-x.y`
|
||||
|
||||
* If your version is older and e.g. equals version 1.2.0 then the name of the
|
||||
- If your version is older and e.g. equals version 1.2.0 then the name of the
|
||||
branch is stable-1.2.
|
||||
* No support for minor- and security bug fixes.
|
||||
- No support for minor- and security bug fixes.
|
||||
|
||||
## Packages
|
||||
|
||||
* Zammad packages are built on [packager.io](https://packager.io).
|
||||
* You can find all Zammad packages [here](https://packager.io/gh/zammad/zammad).
|
||||
* Builds of new packages are triggered with every push to our GitHub repo
|
||||
* If you fork the Zammad repo, you can use packager.io to get builds for your fork
|
||||
* Just change the file `.pkgr.yml` to fit your needs
|
||||
- Zammad packages are built on [packager.io](https://packager.io).
|
||||
- You can find all Zammad packages [here](https://packager.io/gh/zammad/zammad).
|
||||
- Builds of new packages are triggered with every push to our GitHub repo
|
||||
- If you fork the Zammad repo, you can use packager.io to get builds for your fork
|
||||
- Just change the file `.pkgr.yml` to fit your needs
|
||||
|
||||
@@ -2,11 +2,13 @@
|
||||
|
||||
## Development Environment
|
||||
|
||||
Please make sure that you setup your system correctly by following our "[**How to set up a development environment**](how-to-set-up-a-development-environment.md)" guide.
|
||||
Please make sure that you setup your system correctly by following our
|
||||
"[**How to set up a development environment**](how-to-set-up-a-development-environment.md)" guide.
|
||||
|
||||
We emphasize to set following environment variables for developing Zammad.
|
||||
|
||||
* Out of the box, `rails db:seed` is _very_ slow, because it pulls a large library of user interface translations (in over thirty different languages) from a remote server.
|
||||
- Out of the box, `rails db:seed` is _very_ slow, because it pulls a large library of user interface translations
|
||||
(in over thirty different languages) from a remote server.
|
||||
|
||||
To speed this up, use `$Z_LOCALES` to limit the set of downloaded translations.
|
||||
|
||||
@@ -16,61 +18,72 @@ We emphasize to set following environment variables for developing Zammad.
|
||||
|
||||
**Note:** Make sure to include your locale in `$Z_LOCALES`.
|
||||
|
||||
|
||||
## Cloning Repository
|
||||
|
||||
It's possible to clone the repository via HTTPS and SSH.
|
||||
|
||||
```sh
|
||||
# HTTPS
|
||||
$ git clone https://github.com/zammad/zammad.git
|
||||
git clone https://github.com/zammad/zammad.git
|
||||
|
||||
# SSH
|
||||
$ git clone git@github.com:zammad/zammad.git
|
||||
git clone git@github.com:zammad/zammad.git
|
||||
```
|
||||
|
||||
## Initializing Zammad
|
||||
|
||||
After the installation of the correct Ruby version (see [**here**](../development_environment/index.md#rvm)), the following command can be used to install all Ruby dependencies:
|
||||
After the installation of the correct Ruby version (see [**here**](../development_environment/index.md#rvm)), the
|
||||
following command can be used to install all Ruby dependencies:
|
||||
|
||||
```sh
|
||||
$ bundle config set --local without 'mysql'
|
||||
$ bundle install
|
||||
bundle config set --local without 'mysql'
|
||||
bundle install
|
||||
```
|
||||
|
||||
We at Zammad like to work in an efficient way, therefore we have some `Rake` tasks to speed up setting up/refreshing a Zammad installation:
|
||||
We at Zammad like to work in an efficient way, therefore we have some `Rake` tasks to speed up setting up/refreshing a
|
||||
Zammad installation:
|
||||
|
||||
```sh
|
||||
$ rails zammad:bootstrap:init # on a fresh install
|
||||
$ rails zammad:bootstrap:reset # on an existing install
|
||||
rails zammad:bootstrap:init # on a fresh install
|
||||
rails zammad:bootstrap:reset # on an existing install
|
||||
```
|
||||
|
||||
The following sections describe in detail the steps automated by the rake tasks above. If you’re not too concerned about what’s going on under the hood,
|
||||
The following sections describe in detail the steps automated by the rake tasks above. If you’re not too concerned about
|
||||
what’s going on under the hood,
|
||||
skip ahead to [**Launching Zammad**](#launching-zammad).
|
||||
|
||||
### `database.yml`
|
||||
|
||||
The official repository does not include a `config/database.yml` file, because the contents of this file may vary from one developer to another, _e.g.,_ for different login credentials or different DB backends. Therefore we decided to exclude it from the repo to reduce the risk of someone accidentally committing such changes.
|
||||
The official repository does not include a `config/database.yml` file, because the contents of this file may vary from
|
||||
one developer to another, _e.g.,_ for different login credentials or different DB backends. Therefore we decided to
|
||||
exclude it from the repo to reduce the risk of someone accidentally committing such changes.
|
||||
|
||||
However, a working sample is provided in the `config/database` directory:
|
||||
|
||||
```sh
|
||||
$ cp config/database/database.yml config/database.yml
|
||||
cp config/database/database.yml config/database.yml
|
||||
```
|
||||
|
||||
### (Bypassing) The setup wizard
|
||||
|
||||
Zammad requires some extra initialization beyond the standard `rails db:` rake tasks (`create` / `migrate` / `seed`). If you visit the homepage after running those tasks and starting the server, you will be presented with a setup wizard like the one below:
|
||||
Zammad requires some extra initialization beyond the standard `rails db:` rake tasks (`create` / `migrate` / `seed`).
|
||||
If you visit the homepage after running those tasks and starting the server, you will be presented with a setup wizard
|
||||
like the one below:
|
||||
|
||||
|
||||
|
||||
The wizard can be time-consuming to go through (for instance, you have the option to enter and validate SMTP credentials for outgoing emails), but you can’t access the main dashboard (below) or interact with the rest of the app until you complete it.
|
||||
The wizard can be time-consuming to go through (for instance, you have the option to enter and validate SMTP credentials
|
||||
for outgoing emails), but you can’t access the main dashboard (below) or interact with the rest of the app until you
|
||||
complete it.
|
||||
|
||||
|
||||
|
||||
You should click through the wizard just once, just to get a sense of what our users go through — but if we had to do this _every time_ we reset the database, we’d never get any actual work done. So, Zammad includes a feature called the **auto-wizard** to load the application with a set of predefined values instead.
|
||||
You should click through the wizard just once, just to get a sense of what our users go through — but if we had to do
|
||||
this _every time_ we reset the database, we’d never get any actual work done. So, Zammad includes a feature called the
|
||||
**auto-wizard** to load the application with a set of predefined values instead.
|
||||
|
||||
The auto-wizard can either be run from the Rails console or triggered by a page visit in the browser, but either way, it needs two things to work:
|
||||
The auto-wizard can either be run from the Rails console or triggered by a page visit in the browser, but either way,
|
||||
it needs two things to work:
|
||||
|
||||
1. a clean, freshly-seeded database, and
|
||||
2. an `auto_wizard.json` config file (like the one stored in `/contrib`)
|
||||
@@ -80,14 +93,14 @@ The auto-wizard can either be run from the Rails console or triggered by a page
|
||||
#### Option 1: Rake task
|
||||
|
||||
```sh
|
||||
$ rake zammad:setup:auto_wizard
|
||||
rake zammad:setup:auto_wizard
|
||||
```
|
||||
|
||||
#### Option 2: Running via `rails console`
|
||||
|
||||
```sh
|
||||
$ cp contrib/auto_wizard_test.json auto_wizard.json
|
||||
$ rails console
|
||||
cp contrib/auto_wizard_test.json auto_wizard.json
|
||||
rails console
|
||||
Loading development environment (Rails 5.1.5)
|
||||
>> AutoWizard.setup
|
||||
=> #<User:0x000056220b14db50...
|
||||
@@ -100,26 +113,30 @@ Loading development environment (Rails 5.1.5)
|
||||
#### Option 3: Running in-browser
|
||||
|
||||
```sh
|
||||
$ cp contrib/auto_wizard_test.json auto_wizard.json
|
||||
$ rails server
|
||||
cp contrib/auto_wizard_test.json auto_wizard.json
|
||||
rails server
|
||||
```
|
||||
|
||||
Then, visit <http://localhost:3000/#getting_started/auto_wizard>.
|
||||
|
||||
## Launching Zammad
|
||||
|
||||
There are **three separate processes** that support the Zammad application (a _web server_, _websocket server_ and _background-worker_). The web server alone is sufficient to launch the application, but without the other two, critical
|
||||
There are **three separate processes** that support the Zammad application (a _web server_, _websocket server_ and
|
||||
_background-worker_). The web server alone is sufficient to launch the application, but without the other two, critical
|
||||
features will not work.
|
||||
|
||||
### Using the Procfile
|
||||
|
||||
Zammad uses a [`Procfile`](https://devcenter.heroku.com/articles/procfile) to specify the different processes required by the application. We are using [**forego**](https://github.com/ddollar/forego)) to read the `Procfile` and spawn each process listed within it:
|
||||
Zammad uses a [`Procfile`](https://devcenter.heroku.com/articles/procfile) to specify the different processes required
|
||||
by the application. We are using [**forego**](https://github.com/ddollar/forego)) to read the `Procfile` and spawn each
|
||||
process listed within it:
|
||||
|
||||
```sh
|
||||
$ forego start -r
|
||||
forego start -r
|
||||
```
|
||||
|
||||
Note the `-r` switch which means that if any one of the services are gracefully stopped (e.g. due to a configuration change), `forego` will automatically respawn them for you.
|
||||
Note the `-r` switch which means that if any one of the services are gracefully stopped (e.g. due to a configuration
|
||||
change), `forego` will automatically respawn them for you.
|
||||
|
||||
### Manually
|
||||
|
||||
@@ -127,16 +144,17 @@ Of course, you can always just start and stop all the processes by hand:
|
||||
|
||||
```sh
|
||||
# in three separate terminal windows
|
||||
$ rails server
|
||||
$ script/background-worker.rb start
|
||||
$ script/websocket-server.rb start
|
||||
rails server
|
||||
script/background-worker.rb start
|
||||
script/websocket-server.rb start
|
||||
```
|
||||
|
||||
## Login
|
||||
|
||||
Once you’ve launched Zammad, access the app in your browser by visiting [**localhost:3000**](http://localhost:3000) and log in using following credentials:
|
||||
Once you’ve launched Zammad, access the app in your browser by visiting [**localhost:3000**](http://localhost:3000) and
|
||||
log in using following credentials:
|
||||
|
||||
```
|
||||
```plain
|
||||
User: admin@example.com
|
||||
Pasword: test
|
||||
```
|
||||
|
||||
@@ -86,7 +86,8 @@ To ensure a well-readable and maintainable code base, we're using linting tools
|
||||
- [ESLint](https://eslint.org/)
|
||||
- [Markdownlint](https://github.com/DavidAnson/markdownlint)
|
||||
|
||||
There is also a dependency on [Docker](https://www.docker.com/) for some linting tasks, make sure it's available on your system.
|
||||
There is also a dependency on [Docker](https://www.docker.com/) for some linting tasks, make sure it's available on your
|
||||
system.
|
||||
|
||||
For Linux and macOS:
|
||||
|
||||
@@ -151,38 +152,46 @@ All Ruby dependencies (including development dependencies) can be installed easi
|
||||
For Linux and macOS:
|
||||
|
||||
```screen
|
||||
$ cd </path/to/zammad-develop/>
|
||||
$ bundle install
|
||||
cd </path/to/zammad-develop/>
|
||||
bundle install
|
||||
```
|
||||
|
||||
## Using HTTPS
|
||||
|
||||
Zammad uses the gem `localhost` to automatically generate self-signed certificates. This will place `~/.local/state/localhost.rb/localhost.crt` and `~/.local/state/localhost.rb/localhost.key` files if needed. Then you can use one of the following commands to start the development server:
|
||||
Zammad uses the gem `localhost` to automatically generate self-signed certificates. This will place
|
||||
`~/.local/state/localhost.rb/localhost.crt` and `~/.local/state/localhost.rb/localhost.key` files if needed. Then you
|
||||
can use one of the following commands to start the development server:
|
||||
|
||||
```sh
|
||||
$ VITE_RUBY_HOST=0.0.0.0 VITE_RUBY_HTTPS=true RAILS_ENV=development forego start -r -f Procfile.dev-https
|
||||
VITE_RUBY_HOST=0.0.0.0 VITE_RUBY_HTTPS=true RAILS_ENV=development forego start -r -f Procfile.dev-https
|
||||
# or
|
||||
$ pnpm dev:https
|
||||
pnpm dev:https
|
||||
```
|
||||
|
||||
The application will be listening on [https://localhost:3000](https://localhost:3000).
|
||||
|
||||
### Self-signed Certificate Exemption
|
||||
|
||||
By default, the browser will not allow you to access an HTTPS site with a self-signed certificate. You will need to add an exemption by clicking on **Advanced** and choosing **Proceed (unsafe)** or **Accept the Risk and Continue**.
|
||||
By default, the browser will not allow you to access an HTTPS site with a self-signed certificate. You will need to add
|
||||
an exemption by clicking on **Advanced** and choosing **Proceed (unsafe)** or **Accept the Risk and Continue**.
|
||||
|
||||
In Firefox, you will also have to add an exemption for WebSocket addresses, since they use a different port. Visit [https://localhost:6042](https://localhost:6042) and [https://localhost:3036](https://localhost:3036) to kick-start the process and then try to reload the app.
|
||||
In Firefox, you will also have to add an exemption for WebSocket addresses, since they use a different port. Visit
|
||||
[https://localhost:6042](https://localhost:6042) and [https://localhost:3036](https://localhost:3036) to kick-start the
|
||||
process and then try to reload the app.
|
||||
|
||||
### Signed Certificate Issued via Let's Encrypt
|
||||
|
||||
Sometimes, using self-signed certificates might not be enough, due to some platforms still not executing the app in a secure context. You can issue a proper signed certificate via [Let's Encrypt](https://letsencrypt.org/) service for free. As a pre-requisite, you will need an access to a DNS table of a custom domain and a local instance of [Docker](https://www.docker.com/).
|
||||
Sometimes, using self-signed certificates might not be enough, due to some platforms still not executing the app in a
|
||||
secure context. You can issue a proper signed certificate via [Let's Encrypt](https://letsencrypt.org/) service for
|
||||
free. As a pre-requisite, you will need an access to a DNS table of a custom domain and a local instance of
|
||||
[Docker](https://www.docker.com/).
|
||||
|
||||
First, decide on a subdomain for your app, i.e. if you own `example.com` you may want to use `localhost.example.com`.
|
||||
|
||||
Next, run the following Docker container to start the DNS01 challenge process to verify you own the domain in question:
|
||||
|
||||
```sh
|
||||
$ docker run --rm -it -v /path/to/certs:/etc/letsencrypt certbot/dns-cloudflare certonly --manual --preferred-challenges dns --email you@example.com --agree-tos --no-eff-email --key-type rsa -d localhost.example.com
|
||||
docker run --rm -it -v /path/to/certs:/etc/letsencrypt certbot/dns-cloudflare certonly --manual --preferred-challenges dns --email you@example.com --agree-tos --no-eff-email --key-type rsa -d localhost.example.com
|
||||
```
|
||||
|
||||
Where:
|
||||
@@ -191,24 +200,31 @@ Where:
|
||||
- `you@example.com` is your email address
|
||||
- `localhost.example.com` is the FQDN of your subdomain
|
||||
|
||||
When asked to deploy a DNS TXT record by certbot, open the DNS table of your domain. Add a TXT record with suggested name in form of `_acme-challenge.localhost.example.com.` and suggested random value. Save the record and wait some seconds for changes to propagate (this may depend on your DNS host).
|
||||
When asked to deploy a DNS TXT record by certbot, open the DNS table of your domain. Add a TXT record with suggested
|
||||
name in form of `_acme-challenge.localhost.example.com.` and suggested random value. Save the record and wait some
|
||||
seconds for changes to propagate (this may depend on your DNS host).
|
||||
|
||||
Then, press Enter to continue the challenge process. If the certbot identifies your DNS record, it will automatically issue an appropriate certificate. Do not proceed if there was an error logged, resolve it first.
|
||||
Then, press Enter to continue the challenge process. If the certbot identifies your DNS record, it will automatically
|
||||
issue an appropriate certificate. Do not proceed if there was an error logged, resolve it first.
|
||||
|
||||
Next, backup your current self-signed certificate files (if they exist) and create symbolic links to the new ones:
|
||||
|
||||
```sh
|
||||
$ cd ~/.local/state/localhost.rb
|
||||
$ mv localhost.crt localhost.crt.self-signed
|
||||
$ mv localhost.key localhost.key.self-signed
|
||||
$ ln -s /path/to/certs/live/localhost.example.com/cert.pem ~/.local/state/localhost.rb/localhost.crt
|
||||
$ ln -s /path/to/certs/live/localhost.example.com/privkey.pem ~/.local/state/localhost.rb/localhost.key
|
||||
cd ~/.local/state/localhost.rb
|
||||
mv localhost.crt localhost.crt.self-signed
|
||||
mv localhost.key localhost.key.self-signed
|
||||
ln -s /path/to/certs/live/localhost.example.com/cert.pem ~/.local/state/localhost.rb/localhost.crt
|
||||
ln -s /path/to/certs/live/localhost.example.com/privkey.pem ~/.local/state/localhost.rb/localhost.key
|
||||
```
|
||||
|
||||
You may need to adjust the paths depending on your subdomain name.
|
||||
|
||||
Next, add an A DNS record for your subdomain that points to your local IP. You can find out your local IP via `ifconfig` or a similar command.
|
||||
Next, add an A DNS record for your subdomain that points to your local IP. You can find out your local IP via
|
||||
`ifconfig` or a similar command.
|
||||
|
||||
For example, if your local IP is `192.168.0.39` and your subdomain is `localhost.example.com`, add an A DNS record with the name of `localhost` and point it to `192.168.0.39`. This will allow you to access the app from within your local network only by using the proper FQDN: perfect for testing the app on mobile devices.
|
||||
For example, if your local IP is `192.168.0.39` and your subdomain is `localhost.example.com`, add an A DNS record with
|
||||
the name of `localhost` and point it to `192.168.0.39`. This will allow you to access the app from within your local
|
||||
network only by using the proper FQDN: perfect for testing the app on mobile devices.
|
||||
|
||||
Finally, start the development server with `pnpm dev:https` command. You can now access the app via [https://localhost.example.com:3000](https://localhost.example.com:3000) and it should show up as a trusted site.
|
||||
Finally, start the development server with `pnpm dev:https` command. You can now access the app via
|
||||
[https://localhost.example.com:3000](https://localhost.example.com:3000) and it should show up as a trusted site.
|
||||
|
||||
@@ -3,15 +3,16 @@
|
||||
## Table of Contents
|
||||
|
||||
1. [Introduction](#introduction)
|
||||
2. [Setup](##setup)
|
||||
2. [Setup](#setup)
|
||||
3. [Docs](#docs)
|
||||
3. [Generating a Template](#creating-a-template)
|
||||
4. [Generating a Template](#generating-a-template)
|
||||
|
||||
## Introduction
|
||||
|
||||
Hygen is a powerful, extensible code generator that helps us quickly create files and boilerplate code based on customizable templates.
|
||||
This document provides an overview of how to use Hygen in Zammad, including setup, template creation, and common usage patterns.
|
||||
|
||||
Hygen is a powerful, extensible code generator that helps us quickly create files and boilerplate code based on
|
||||
customizable templates.
|
||||
This document provides an overview of how to use Hygen in Zammad, including setup, template creation, and common usage
|
||||
patterns.
|
||||
|
||||
## Setup
|
||||
|
||||
@@ -25,7 +26,7 @@ pnpm generate:install
|
||||
|
||||
[Hygen official docs](https://www.hygen.io/docs/templates/)
|
||||
|
||||
### Generating a template
|
||||
## Generating a template
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -37,6 +38,7 @@ pnpm generate:install
|
||||
```
|
||||
|
||||
**Steps:**
|
||||
|
||||
1. Open the terminal
|
||||
2. Run the command f.e `pnpm generate:generic-component`
|
||||
3. Follow the CI prompts
|
||||
@@ -48,11 +50,13 @@ To create a new template:
|
||||
⬇️
|
||||
|
||||
**Steps:**
|
||||
|
||||
1. Navigate into `./dev/hygen/templates/new`
|
||||
2. Create a prompt.js file
|
||||
3. Add additional configurations in lib.config.js
|
||||
4. Create a template file in the directory
|
||||
|
||||
**Note:**
|
||||
|
||||
- For example directory `new` -> specifies generator name
|
||||
- `generic-component` -> action to be performed
|
||||
|
||||
@@ -1,14 +1,15 @@
|
||||
# Developer Manual for Zammad
|
||||
|
||||
Welcome to the developer docs of Zammad. 👋 This is a work in progress, and you're encouraged to contribute and improve it.
|
||||
Welcome to the developer docs of Zammad. 👋 This is a work in progress, and you're encouraged to contribute and improve
|
||||
it.
|
||||
|
||||
# Development Environment
|
||||
## Development Environment
|
||||
|
||||
- [How to set up a development environment](development_environment/how-to-set-up-a-development-environment.md)
|
||||
- [Getting started](development_environment/getting-started.md)
|
||||
- [Basic information](development_environment/basic-information.md)
|
||||
|
||||
# Standards & Best Practices
|
||||
## Standards & Best Practices
|
||||
|
||||
- [Code Style Guide](standards/code-style-guide.md)
|
||||
- [How to design tests](standards/how-to-design-tests.md)
|
||||
@@ -18,7 +19,7 @@ Welcome to the developer docs of Zammad. 👋 This is a work in progress, and yo
|
||||
- [How to rebuild the chat](standards/how-to-rebuild-the-chat.md)
|
||||
- [How to use forms](standards/how-to-use-forms.md)
|
||||
|
||||
# Cookbook / Recipes
|
||||
## Cookbook / Recipes
|
||||
|
||||
- [How to diagnose email bugs](cookbook/how-to-diagnose-email-bugs.md)
|
||||
- [How to Debug Zammad Processes](cookbook/how-to-debug-zammad-processes.md)
|
||||
@@ -29,10 +30,12 @@ Welcome to the developer docs of Zammad. 👋 This is a work in progress, and yo
|
||||
- [How to test with Vitest and Cypress](cookbook/how-to-test-with-vitest-and-cypress.md)
|
||||
- [How to test the development version of Zammad via Docker](cookbook/how-to-test-develop-with-docker.md)
|
||||
|
||||
# How to Contribute
|
||||
## How to Contribute
|
||||
|
||||
We live & love Open Source and therefore we encourage our community to contribute to the development of Zammad.
|
||||
|
||||
You could simply to do this by fixing a reported [issue](https://github.com/zammad/zammad/issues) or by implementing an enhancement.
|
||||
You could simply to do this by fixing a reported [issue](https://github.com/zammad/zammad/issues) or by implementing an
|
||||
enhancement.
|
||||
|
||||
For the workflow how to contribute, please check [the official GitHub documentation](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request).
|
||||
For the workflow how to contribute, please check
|
||||
[the official GitHub documentation](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request).
|
||||
|
||||
@@ -5,10 +5,11 @@
|
||||
### Enforcing style guides
|
||||
|
||||
Our coding standards are enforced in the internal CI by various tools like Rubocop and ESLint.
|
||||
To make sure you always keep them in mind, you can use git hooks based on [**overcommit**](https://github.com/sds/overcommit) for this.
|
||||
To make sure you always keep them in mind, you can use git hooks based on
|
||||
[**overcommit**](https://github.com/sds/overcommit) for this.
|
||||
|
||||
```screen
|
||||
$ overcommit --install
|
||||
overcommit --install
|
||||
```
|
||||
|
||||
This will execute several checks on the changed files whenever you commit.
|
||||
@@ -18,31 +19,37 @@ Linters can also be run manually:
|
||||
|
||||
```screen
|
||||
# Robocop
|
||||
$ bundle exec rubocop --parallel
|
||||
bundle exec rubocop --parallel
|
||||
|
||||
# Type checks, ESLint & Stylelint
|
||||
$ pnpm lint
|
||||
# Type checks, ESLint, Stylelint & Markdownlint
|
||||
pnpm lint
|
||||
|
||||
# Type checks, ESLint & Stylelint with automatic fixing
|
||||
$ pnpm lint:fix
|
||||
# Type checks, ESLint, Stylelint & Markdownlint with automatic fixing
|
||||
pnpm lint:fix
|
||||
|
||||
# Just type checking
|
||||
$ pnpm lint:ts
|
||||
pnpm lint:ts
|
||||
|
||||
# Just ESLint checks
|
||||
$ pnpm lint:js
|
||||
pnpm lint:js
|
||||
|
||||
# Just ESLint checks with automatic fixing
|
||||
$ pnpm lint:js:fix
|
||||
pnpm lint:js:fix
|
||||
|
||||
# Just Stylelint checks
|
||||
$ pnpm lint:css
|
||||
pnpm lint:css
|
||||
|
||||
# Just Stylelint checks with automatic fixing
|
||||
$ pnpm lint:css:fix
|
||||
pnpm lint:css:fix
|
||||
|
||||
# Just Markdownlint checks
|
||||
pnpm lint:md
|
||||
|
||||
# Just Markdownlint checks with automatic fixing
|
||||
pnpm lint:md:fix
|
||||
|
||||
# Coffeelint
|
||||
$ coffeelint --rules ./.dev/coffeelint/rules/* app/
|
||||
coffeelint --rules ./.dev/coffeelint/rules/* app/
|
||||
```
|
||||
|
||||
### Wording
|
||||
@@ -66,30 +73,33 @@ Rubocop will tell you. Don't forget to run it. Here are some additional tips.
|
||||
|
||||
### Naming of Concerns
|
||||
|
||||
#### Has*
|
||||
#### `Has*`
|
||||
|
||||
The methods are doing model related functions and events.
|
||||
This area is mainly used to do changes to other related objects.
|
||||
|
||||
For example, a model
|
||||
* gets some new events to clear the cache in the cache object
|
||||
* will get some new events to verify attachments in the store object
|
||||
* will modify the external sync object after destroying an object
|
||||
|
||||
#### Checks*
|
||||
- gets some new events to clear the cache in the cache object
|
||||
- will get some new events to verify attachments in the store object
|
||||
- will modify the external sync object after destroying an object
|
||||
|
||||
#### `Checks*`
|
||||
|
||||
The code contains hooks to events (e.g. `after_commit`), validations or another pre/post function checks.
|
||||
|
||||
For example:
|
||||
* added a check to verify the length of an attribute
|
||||
|
||||
#### Can*
|
||||
- added a check to verify the length of an attribute
|
||||
|
||||
#### `Can*`
|
||||
|
||||
The code contains new functions without any relations to any hook or event.
|
||||
|
||||
For example, a model will get some new util functions
|
||||
* which can be used to read additional assets
|
||||
* to handle parameters in a more efficient way
|
||||
|
||||
- which can be used to read additional assets
|
||||
- to handle parameters in a more efficient way
|
||||
|
||||
### RSpec
|
||||
|
||||
@@ -110,19 +120,20 @@ lowerCamelCase_ e.g. fileSize
|
||||
|
||||
#### Files-Names
|
||||
|
||||
##### Vue-Components:
|
||||
##### Vue Components
|
||||
|
||||
UpperCamelCase: e.g. CommonDateTime.vue
|
||||
|
||||
##### Typescript-Files / Other
|
||||
##### Typescript Files / Other
|
||||
|
||||
##### Vue Template Refs:
|
||||
##### Vue Template Refs
|
||||
|
||||
- Use SnakeCase for template ref f.g `ref="resize-line"`
|
||||
- Component instance variables should contain `${ComponentName}Instance`
|
||||
- Prefer to use `useTemplateRef` over `ref` for template references
|
||||
|
||||
###### useTemplateRef
|
||||
|
||||
[docs](https://vuejs.org/api/composition-api-helpers.html#usetemplateref)
|
||||
|
||||
```vue
|
||||
@@ -144,6 +155,7 @@ const listElement = useTemplateRef('list')
|
||||
```
|
||||
|
||||
###### ref
|
||||
|
||||
[docs](https://vuejs.org/api/reactivity-core.html#ref)
|
||||
|
||||
```vue
|
||||
@@ -174,7 +186,7 @@ TBD
|
||||
|
||||
UpperCamelCase:
|
||||
|
||||
```
|
||||
```plain
|
||||
<div>
|
||||
<CommonDateTime ... />
|
||||
<CommonDateTime>...</CommonDateTime>
|
||||
|
||||
@@ -5,9 +5,9 @@
|
||||
Please provide a migration name (no spacings, special characters) like in the example below.
|
||||
|
||||
```screen
|
||||
$ rails generate migration Issue1337IssueDescription
|
||||
invoke active_record
|
||||
create db/migrate/20220715094714_issue1337_issue_description.rb
|
||||
rails generate migration Issue1337IssueDescription
|
||||
invoke active_record
|
||||
create db/migrate/20220715094714_issue1337_issue_description.rb
|
||||
```
|
||||
|
||||
## 2. Apply Zammad patch
|
||||
@@ -16,13 +16,14 @@ Zammad's custom seeding/migration handling require a piece of code
|
||||
to be added to the start of all new migrations.
|
||||
|
||||
```ruby
|
||||
# return if it's a new setup
|
||||
return if !Setting.exists?(name: 'system_init_done')
|
||||
# return if it's a new setup
|
||||
return if !Setting.exists?(name: 'system_init_done')
|
||||
```
|
||||
|
||||
## 3. Add the actual migration content
|
||||
|
||||
Your initial migration file now should like so:
|
||||
|
||||
```ruby
|
||||
class Issue1337IssueDescription < ActiveRecord::Migration[6.1]
|
||||
def change
|
||||
@@ -51,4 +52,5 @@ Any changes that involve database content must be applied in the corresponding [
|
||||
|
||||
Now you're ready to test the migration (`rake db:migrate`) and installation/seeding (`rake zammad:db:reset`).
|
||||
|
||||
If your newly created migration is not running fine, don't be worried. You could simply do a rollback via `rake db:rollback STEP=1` and re-run the migration.
|
||||
If your newly created migration is not running fine, don't be worried. You could simply do a rollback via
|
||||
`rake db:rollback STEP=1` and re-run the migration.
|
||||
|
||||
@@ -4,25 +4,30 @@ Icons should be added to the [public icons folder](/public/assets/images/icons).
|
||||
|
||||
## Graphic Dimensions
|
||||
|
||||
You should adjust the SSO graphic dimensions to `29x24` using a vector graphics program so that it fits in with the other ones.
|
||||
You should adjust the SSO graphic dimensions to `29x24` using a vector graphics program so that it fits in with the
|
||||
other ones.
|
||||
|
||||
## Colors
|
||||
|
||||
There are two colors that act as variables so that they can get replaced via CSS. The main one is `#50E3C2` that can get overwritten in CSS via `fill` and the secondary is `#BD0FE1`, that can be overwritten in css via `color`. The SSO graphics (top right corner) don't use these variables so you probably won't need them either.
|
||||
There are two colors that act as variables so that they can get replaced via CSS. The main one is `#50E3C2` that can
|
||||
get overwritten in CSS via `fill` and the secondary is `#BD0FE1`, that can be overwritten in css via `color`. The SSO
|
||||
graphics (top right corner) don't use these variables so you probably won't need them either.
|
||||
|
||||
## Build Process
|
||||
|
||||
See [`public/assets/images/README.md`](/public/assets/images/README.md):
|
||||
|
||||
```
|
||||
$ pnpm install
|
||||
$ pnpm exec gulp build
|
||||
```sh
|
||||
pnpm install
|
||||
pnpm exec gulp build
|
||||
[14:08:17] Using gulpfile zammad/public/assets/images/gulpfile.js
|
||||
[14:08:17] Starting 'build'...
|
||||
[14:08:17] Finished 'build' after 7.48 ms
|
||||
```
|
||||
|
||||
Now the icon should be included in `icons.svg`.
|
||||
|
||||
## Attribution
|
||||
|
||||
Add the author, url and license to `LICENSE-ICONS-3RD-PARTY.json`. If you have a local server running that supports php, there is a UI for this: `contrib/edit-icon-license-list.php`
|
||||
Add the author, url and license to `LICENSE-ICONS-3RD-PARTY.json`. If you have a local server running that supports
|
||||
php, there is a UI for this: `contrib/edit-icon-license-list.php`
|
||||
|
||||
@@ -35,21 +35,33 @@ Writing strings that can be translated well and are a pleasure to read for the e
|
||||
|
||||
#### Bad Examples
|
||||
|
||||
- `lock` - this English word is ambiguous, it can be a noun (`a lock`), an infinitive (`to lock`) and an imperative (`lock this!`). That makes it impossible to translate it properly.
|
||||
- `lock` - this English word is ambiguous, it can be a noun (`a lock`), an infinitive (`to lock`) and an imperative
|
||||
(`lock this!`). That makes it impossible to translate it properly.
|
||||
- `No email!` - this error message is not understandable for an end user.
|
||||
|
||||
#### Good Practices
|
||||
|
||||
- *Talk to the end user.* Imagine you are a non-technical end user of Zammad. Would you understand the error messages? Use natural, respectful language.
|
||||
- *Write at least two words.* Whenever possible, avoid creating single-word strings. This will reduce ambiguity drastically.
|
||||
- *Include punctuation.* Strings should include punctuation like final stops (`This is a sentence.`) or colons (`My label:`) as part of the translatable string. This punctuation might look different in some languages and should therefore not be hardcoded.
|
||||
- *Use placeholders, don't concatenate strings.* Bad: `"Open" + ticket_number`, good: `"Open ticket %s"` (and pass `ticket_number` as parameter). It's almost always a good idea to produce such slightly longer strings with placeholders. That helps translators to understand them and allows them to change the position of the placeholders in translations.
|
||||
- *Personal pronouns only for the user*: When referring to the user, `you` and `my` are fine (`Do you want to proceed?`, `My escalated tickets`). Other pronouns should be avoided, especially when talking about the software/system itself. Bad: `I / we could not generate the key`. Use the passive (`The key could not be generated`) or talk about `Zammad` instead (`Zammad does not support OTRS BPM processes`).
|
||||
- _Talk to the end user._ Imagine you are a non-technical end user of Zammad. Would you understand the error messages?
|
||||
Use natural, respectful language.
|
||||
- _Write at least two words._ Whenever possible, avoid creating single-word strings. This will reduce ambiguity
|
||||
drastically.
|
||||
- _Include punctuation._ Strings should include punctuation like final stops (`This is a sentence.`) or colons
|
||||
(`My label:`) as part of the translatable string. This punctuation might look different in some languages and should
|
||||
therefore not be hardcoded.
|
||||
- _Use placeholders, don't concatenate strings._ Bad: `"Open" + ticket_number`, good: `"Open ticket %s"` (and pass
|
||||
`ticket_number` as parameter). It's almost always a good idea to produce such slightly longer strings with
|
||||
placeholders. That helps translators to understand them and allows them to change the position of the placeholders in
|
||||
translations.
|
||||
- _Personal pronouns only for the user_: When referring to the user, `you` and `my` are fine (`Do you want to proceed?`,
|
||||
`My escalated tickets`). Other pronouns should be avoided, especially when talking about the software/system itself.
|
||||
Bad: `I / we could not generate the key`. Use the passive (`The key could not be generated`) or talk about `Zammad`
|
||||
instead (`Zammad does not support OTRS BPM processes`).
|
||||
|
||||
### Weblate Process Overview
|
||||
|
||||
- The codebase has a translation catalog file [i18n/zammad.pot](zammad.pot), which must be kept up-to-date.
|
||||
- Weblate automatically picks this file up from git and updates its database. Now translators see the new/changed strings and can work on them.
|
||||
- Weblate automatically picks this file up from git and updates its database. Now translators see the new/changed
|
||||
strings and can work on them.
|
||||
- From time to time, Weblate pushes the new/updated translations via merge request to git.
|
||||
- After the merge, the translation files in `i18n/zammad.*.po` are updated.
|
||||
- Zammad will pick them up as soon as `Translation.sync` gets called, which happens for example during a package update.
|
||||
@@ -75,7 +87,8 @@ To test any changes made to translations in Weblate that are not yet published t
|
||||
you can use this workflow:
|
||||
|
||||
- Download the current state of the language from Weblate as po file.
|
||||
- Save it locally in the Zammad folder as `i18n/zammad.pt-br.po` (for `pt-br` in this case, use corresponding file names for other languages).
|
||||
- Save it locally in the Zammad folder as `i18n/zammad.pt-br.po` (for `pt-br` in this case, use corresponding file
|
||||
names for other languages).
|
||||
- Run `rails r Translation.sync` to import the latest state to the database.
|
||||
- Now the changes should appear in the GUI.
|
||||
|
||||
|
||||
@@ -2,9 +2,12 @@
|
||||
|
||||
## Basics
|
||||
|
||||
Forms in Zammad are based on [FormKit](https://formkit.com/) and the documentation is referenced in the following paragraphs.
|
||||
Forms in Zammad are based on [FormKit](https://formkit.com/) and the documentation is referenced in the following
|
||||
paragraphs.
|
||||
|
||||
They are defined by the `schema`. The schema data describes the form containing all needed form fields, e.g. [the ticket creation screen](https://github.com/zammad/zammad/blob/develop/app/frontend/apps/mobile/pages/ticket/views/TicketCreate.vue#L121). For more information, please see the [Formkit schema essentials description](https://formkit.com/essentials/schema).
|
||||
They are defined by the `schema`. The schema data describes the form containing all needed form fields, e.g.
|
||||
[the ticket creation screen](https://github.com/zammad/zammad/blob/develop/app/frontend/apps/mobile/pages/ticket/views/TicketCreate.vue#L121).
|
||||
For more information, please see the [Formkit schema essentials description](https://formkit.com/essentials/schema).
|
||||
|
||||
## Usage of Reactivity
|
||||
|
||||
@@ -12,9 +15,12 @@ The forms provide reactivity to modify the form and form fields on events, e.g.
|
||||
|
||||
### Schema Data
|
||||
|
||||
In addition to the static schema, the `Form` component can also include a `schemaData` prop. Values from the data object and properties can then be referenced, and your schema will maintain the reactivity of the original data object.
|
||||
In addition to the static schema, the `Form` component can also include a `schemaData` prop. Values from the data object
|
||||
and properties can then be referenced, and your schema will maintain the reactivity of the original data object.
|
||||
|
||||
To reference a value from the data object, you simply use `$` followed by the property name from the data object. References can be used in the schema `attrs`, `props`, `conditionals`, and as children. Please have a look at the [FormKit references page](https://formkit.com/essentials/schema#references).
|
||||
To reference a value from the data object, you simply use `$` followed by the property name from the data object.
|
||||
References can be used in the schema `attrs`, `props`, `conditionals`, and as children. Please have a look at the
|
||||
[FormKit references page](https://formkit.com/essentials/schema#references).
|
||||
|
||||
In our implementation, the current form values are always available as `$values`.
|
||||
|
||||
@@ -41,9 +47,11 @@ Example (excerpt of static schema)
|
||||
|
||||
The `changeFields` is a reactive extension for the form implementation.
|
||||
|
||||
This is our preferred way of changing the state of fields after a user interacts with the form. This should be manipulated with the `changed` event of the form.
|
||||
This is our preferred way of changing the state of fields after a user interacts with the form. This should be
|
||||
manipulated with the `changed` event of the form.
|
||||
|
||||
A simple use case is to mark some fields as mandatory after a user selects the value `Support Request` in the field `Category`.
|
||||
A simple use case is to mark some fields as mandatory after a user selects the value `Support Request` in the field
|
||||
`Category`.
|
||||
|
||||
### Handlers
|
||||
|
||||
@@ -56,4 +64,5 @@ The form handler supports two execution types:
|
||||
- `Initial`
|
||||
- `FieldChange`
|
||||
|
||||
For a working example of a handler, please have a look at the [ticket signature code](https://github.com/zammad/zammad/blob/develop/app/frontend/shared/composables/useTicketSignature.ts).
|
||||
For a working example of a handler, please have a look at the
|
||||
[ticket signature code](https://github.com/zammad/zammad/blob/develop/app/frontend/shared/composables/useTicketSignature.ts).
|
||||
|
||||
@@ -1 +1,3 @@
|
||||
# i18n
|
||||
|
||||
Please see [this section in the developer manual](../doc/developer_manual/standards/how-to-handle-localization.md).
|
||||
@@ -7,7 +7,7 @@
|
||||
"dev:https": "VITE_RUBY_HOST=0.0.0.0 VITE_RUBY_HTTPS=true RAILS_ENV=development forego start -r -f Procfile.dev-https",
|
||||
"i18n": "rails generate zammad:translation_catalog",
|
||||
"lint": "pnpm lint:ts && pnpm lint:js && pnpm lint:css && pnpm lint:md",
|
||||
"lint:fix": "pnpm lint:ts && pnpm lint:js:fix && pnpm lint:css:fix",
|
||||
"lint:fix": "pnpm lint:ts && pnpm lint:js:fix && pnpm lint:css:fix && pnpm lint:md:fix",
|
||||
"lint:ts": "vue-tsc --noEmit",
|
||||
"lint:js": "pnpm lint:js:cmd app/frontend/ .eslint-plugin-zammad/",
|
||||
"lint:js:cmd": "eslint --cache --cache-location ./tmp/eslintcache.js --cache-strategy content -c .eslintrc.js --ext .js,.ts,.vue",
|
||||
@@ -15,7 +15,7 @@
|
||||
"lint:css": "pnpm lint:css:cmd **/*.{css,vue,scss}",
|
||||
"lint:css:cmd": "stylelint",
|
||||
"lint:css:fix": "pnpm lint:css --fix",
|
||||
"lint:md": "pnpm lint:md:cmd \"*.md\" \"doc/**/*.md\"",
|
||||
"lint:md": "pnpm lint:md:cmd '*.md' '**/*.md' '#node_modules'",
|
||||
"lint:md:fix": "pnpm lint:md --fix",
|
||||
"lint:md:cmd": "docker run -v $PWD:/workdir --rm davidanson/markdownlint-cli2:latest",
|
||||
"test": "VTL_SKIP_AUTO_CLEANUP=true TZ=utc vitest",
|
||||
|
||||
@@ -1,8 +1,10 @@
|
||||
# Recreating the Static Zammad Chat Build
|
||||
# Chat
|
||||
|
||||
```
|
||||
$ pnpm install
|
||||
$ pnpm exec gulp build
|
||||
## Recreating the Static Zammad Chat Build
|
||||
|
||||
```sh
|
||||
pnpm install
|
||||
pnpm exec gulp build
|
||||
[11:13:03] Using gulpfile zammad/public/assets/chat/gulpfile.js
|
||||
[11:13:03] Starting 'build'...
|
||||
[11:13:03] Starting 'js'...
|
||||
@@ -14,11 +16,11 @@ $ pnpm exec gulp build
|
||||
[11:13:03] Finished 'build' after 9.8 ms
|
||||
```
|
||||
|
||||
# Development Mode
|
||||
## Development Mode
|
||||
|
||||
This is useful when developing. Gulp will watch the files for changes and start rebuilds automatically.
|
||||
|
||||
```
|
||||
```sh
|
||||
pnpm exec gulp
|
||||
[11:14:46] Using gulpfile ~/wz/zammad/public/assets/chat/gulpfile.js
|
||||
[11:14:46] Starting 'default'...
|
||||
|
||||
@@ -1,18 +1,20 @@
|
||||
# Recreating the Zammad SVG Icon Store
|
||||
# Images
|
||||
|
||||
```
|
||||
$ pnpm install
|
||||
$ pnpm exec gulp build
|
||||
## Recreating the Zammad SVG Icon Store
|
||||
|
||||
```sh
|
||||
pnpm install
|
||||
pnpm exec gulp build
|
||||
[14:08:17] Using gulpfile zammad/public/assets/images/gulpfile.js
|
||||
[14:08:17] Starting 'build'...
|
||||
[14:08:17] Finished 'build' after 7.48 ms
|
||||
```
|
||||
|
||||
# Development Mode
|
||||
## Development Mode
|
||||
|
||||
This is useful when developing. Gulp will watch the files for changes and start rebuilds automatically.
|
||||
|
||||
```
|
||||
```sh
|
||||
pnpm exec gulp
|
||||
[14:14:46] Using gulpfile ~/wz/zammad/public/assets/image/gulpfile.js
|
||||
[14:14:46] Starting 'default'...
|
||||
|
||||
@@ -1,8 +1,9 @@
|
||||
This directory used to contain an example init.d script for Zammad installations
|
||||
without Systemd. This was discontinued since Zammad now uses non-daemonizing service processes.
|
||||
# Init Script
|
||||
|
||||
If using Systemd is not an option for you, consider using the provided binary packages to install
|
||||
even on systems that don't have Systemd.
|
||||
This directory used to contain an example init.d script for Zammad installations without Systemd. This was discontinued
|
||||
since Zammad now uses non-daemonizing service processes.
|
||||
|
||||
Pull requests with a new init script that handles foreground
|
||||
processes correctly would be welcome as well.
|
||||
If using Systemd is not an option for you, consider using the provided binary packages to install even on systems that
|
||||
don't have Systemd.
|
||||
|
||||
Pull requests with a new init script that handles foreground processes correctly would be welcome as well.
|
||||
|
||||
9
spec/fixtures/files/pgp/generate/README.md
vendored
9
spec/fixtures/files/pgp/generate/README.md
vendored
@@ -4,8 +4,9 @@ This folder contains a shell script to generate various PGP keys for testing pur
|
||||
|
||||
The following files will be (re)generated:
|
||||
|
||||
* `spec/fixtures/files/gpg/*.asc` - private key in ASCII armored format
|
||||
* `spec/fixtures/files/gpg/*.pub.asc` - public key in ASCII armored format
|
||||
* `spec/fixtures/files/gpg/*.passphrase` - private key passphrase
|
||||
- `spec/fixtures/files/gpg/*.asc` - private key in ASCII armored format
|
||||
- `spec/fixtures/files/gpg/*.pub.asc` - public key in ASCII armored format
|
||||
- `spec/fixtures/files/gpg/*.passphrase` - private key passphrase
|
||||
|
||||
To execute the script, simply run `run.sh` in this directory. There is nothing more to it except of having `gpg` binary installed and available in the path.
|
||||
To execute the script, simply run `run.sh` in this directory. There is nothing more to it except of having `gpg` binary
|
||||
installed and available in the path.
|
||||
|
||||
10
spec/fixtures/files/smime/generate/README.md
vendored
10
spec/fixtures/files/smime/generate/README.md
vendored
@@ -1,6 +1,10 @@
|
||||
# Zammad S/MIME test certificate generation
|
||||
|
||||
This folder contains a `docker` image and the required files to generate various S/MIME certificates for testing purposes. These contain CA certificates as regular certificates (1). There is one special certificate that is for multiple emails at once (2). Additionally some already expired CA and certificates are generated (3).
|
||||
For the CA there are `.key` and `.crt` files. For the certificates the `.key`, `.crt` and `.csr` are generated. Additionally a `.secret` file is added that contains the corresponding pass phrase.
|
||||
This folder contains a `docker` image and the required files to generate various S/MIME certificates for testing
|
||||
purposes. These contain CA certificates as regular certificates (1). There is one special certificate that is for
|
||||
multiple emails at once (2). Additionally some already expired CA and certificates are generated (3).
|
||||
For the CA there are `.key` and `.crt` files. For the certificates the `.key`, `.crt` and `.csr` are generated.
|
||||
Additionally a `.secret` file is added that contains the corresponding passphrase.
|
||||
|
||||
These are easily generated by executing the `run.sh` file. There is nothing more to it except of having `docker` installed and running.
|
||||
These are easily generated by executing the `run.sh` file. There is nothing more to it except of having `docker`
|
||||
installed and running.
|
||||
|
||||
@@ -1,2 +1,4 @@
|
||||
This folder holds volatile data and may thus be mounted on volatile file systems
|
||||
like tmpfs / ramdisk. It does not need to be shared in cluster setups.
|
||||
# tmp
|
||||
|
||||
This folder holds volatile data and may thus be mounted on volatile file systems like tmpfs / ramdisk. It does not
|
||||
need to be shared in cluster setups.
|
||||
|
||||
Reference in New Issue
Block a user