-
Notifications
You must be signed in to change notification settings - Fork 379
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add documentation for the product system
- Loading branch information
1 parent
ca3277f
commit 0c71680
Showing
7 changed files
with
263 additions
and
74 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,178 @@ | ||
| Product management | ||
| ================== | ||
|
|
||
|  | ||
|
|
||
| The product system allows a single CodeChecker server to serve multiple | ||
| separate result databases, named "products", under the same IP address and | ||
| authentication domain. | ||
|
|
||
| `CodeChecker server` takes database arguments to initialize a connection to a | ||
| **configuration** database. (See the [User guide](docs/user_guide.md) for | ||
| details.) This configuration database contains which products are managed by | ||
| the server, and contain various other metadata. | ||
|
|
||
| The analysis results are stored in **product** databases. Each product | ||
| database is an isolated storage of results, completely separate, and can be | ||
| added and removed from a server on the fly. | ||
|
|
||
| Command-line tools that are used to access analysis data take an `--url | ||
| PRODUCT_URL` parameter, which specifies the server host, port, and the | ||
| product's unique endpoint in the following format: `localhost:8001/Default`, | ||
| where `Default` is the product's endpoint. See the User guide for further | ||
| details. | ||
|
|
||
| The Web application separates products based on their unique endpoint. The | ||
| home page of the server is the product list, shown above. | ||
|
|
||
| ## First start | ||
|
|
||
| When a CodeChecker server is started with a SQLite configuration database, and | ||
| this database is not yet created (such as when the server is started fresh on | ||
| your computer), CodeChecker will automatically set up a `Default` product, | ||
| with a SQLite database file next to the configuration database, in | ||
| `/home/<username>/.codechecker`. | ||
|
|
||
| This does NOT hold true for PostgreSQL configuration backends. These servers, | ||
| as PostgreSQL is advanced usage, must be configured manually. | ||
|
|
||
| # Managing products through the command-line tool, `CodeChecker cmd` | ||
|
|
||
| Please see the [User guide](docs/user_guide.md) for overview on the `cmd` | ||
| command. | ||
|
|
||
| The `products` subcommand of `CodeChecker cmd` group the actions related to | ||
| product configuration. All these commands take a server `--host` and `--port` | ||
| as their argument, as the commands control a server, and not an individual | ||
| product endpoint. | ||
|
|
||
| ~~~~~~~~~~~~~~~~~~~~~ | ||
| usage: CodeChecker cmd products [-h] [--verbose {info,debug,debug_analyzer}] | ||
| {list,add,del} ... | ||
| CodeChecker organises its databases into products. Each product has an | ||
| individually configured database which stores the analysis results. These | ||
| subcommands are used to manage the products configured by the server. Please | ||
| see the individual subcommands for details. | ||
| optional arguments: | ||
| -h, --help show this help message and exit | ||
| available actions: | ||
| {list,add,del} | ||
| list List products available on the server. | ||
| add Register a new product to the server. | ||
| del Delete a product from the server's products. | ||
| common arguments: | ||
| --host HOST The address of the CodeChecker server to connect to. | ||
| (default: localhost) | ||
| -p PORT, --port PORT The port the server is running on. (default: 8001) | ||
| --verbose {info,debug,debug_analyzer} | ||
| Set verbosity level. (default: info) | ||
| Most of these commands require authentication and appropriate access rights. | ||
| Please see 'CodeChecker cmd login' to authenticate. | ||
| ~~~~~~~~~~~~~~~~~~~~~ | ||
|
|
||
| ## Listing products (`list`) | ||
|
|
||
| ~~~~~~~~~~~~~~~~~~~~~ | ||
| usage: CodeChecker cmd products list [-h] [--host HOST] [-p PORT] | ||
| [-o {plaintext,rows,table,csv,json}] | ||
| [--verbose {info,debug,debug_analyzer}] | ||
| List the name and basic information about products added to the server. The | ||
| 'S' status column of the product is 'E' if the product database is errorneous, | ||
| and 'L' if you don't have access to the product. | ||
| optional arguments: | ||
| -h, --help show this help message and exit | ||
| common arguments: | ||
| -o {plaintext,rows,table,csv,json}, --output {plaintext,rows,table,csv,json} | ||
| The output format to use in showing the data. | ||
| (default: plaintext) | ||
| ~~~~~~~~~~~~~~~~~~~~~ | ||
|
|
||
| ## Adding new product (`add`) | ||
|
|
||
| `add` assigns the unique `PRODUCT_NAME` endpoint with a database connection, | ||
| making a new product available on the server. | ||
|
|
||
| ~~~~~~~~~~~~~~~~~~~~~ | ||
| usage: CodeChecker cmd products add [-h] [-n DISPLAY_NAME] | ||
| [--description DESCRIPTION] | ||
| [--sqlite SQLITE_FILE | --postgresql] | ||
| [--dbaddress DBADDRESS] [--dbport DBPORT] | ||
| [--dbusername DBUSERNAME] | ||
| [--dbpassword DBPASSWORD] | ||
| [--dbname DBNAME] [--host HOST] [-p PORT] | ||
| [--verbose {info,debug,debug_analyzer}] | ||
| PRODUCT_NAME | ||
| Create a new product to be managed by the server by providing the product's | ||
| details and database connection. | ||
| positional arguments: | ||
| PRODUCT_NAME The URL endpoint where clients can access the analysis | ||
| results for this product. | ||
| optional arguments: | ||
| -h, --help show this help message and exit | ||
| -n DISPLAY_NAME, --name DISPLAY_NAME | ||
| A custom display name for the product, which will be | ||
| shown in the viewer. This is purely for decoration and | ||
| user experience, program calls use the PRODUCT_NAME. | ||
| --description DESCRIPTION | ||
| A custom textual description to be shown alongside the | ||
| product. | ||
| database arguments: | ||
| NOTE: These database arguments are relative to the server machine, as it | ||
| is the server which will make the database connection. | ||
| --sqlite SQLITE_FILE Path of the SQLite database file to use. Not absolute | ||
| paths will be relative to the server's | ||
| <CONFIG_DIRECTORY>. (default: <PRODUCT_NAME>.sqlite) | ||
| --postgresql Specifies that a PostgreSQL database is to be used | ||
| instead of SQLite. See the "PostgreSQL arguments" | ||
| section on how to configure the database connection. | ||
| PostgreSQL arguments: | ||
| Values of these arguments are ignored, unless '--postgresql' is specified! | ||
| The database specified here must exist, and be connectible by the server. | ||
| --dbaddress DBADDRESS, --db-host DBADDRESS | ||
| Database server address. (default: localhost) | ||
| --dbport DBPORT, --db-port DBPORT | ||
| Database server port. (default: 5432) | ||
| --dbusername DBUSERNAME, --db-username DBUSERNAME | ||
| Username to use for connection. (default: | ||
| <PRODUCT_NAME>) | ||
| --dbpassword DBPASSWORD, --db-password DBPASSWORD | ||
| Password to use for authenticating the connection. | ||
| (default: ) | ||
| --dbname DBNAME, --db-name DBNAME | ||
| Name of the database to use. (default: <PRODUCT_NAME>) | ||
| ~~~~~~~~~~~~~~~~~~~~~ | ||
|
|
||
| ## Delete a product (`del`) | ||
|
|
||
| ~~~~~~~~~~~~~~~~~~~~~ | ||
| usage: CodeChecker cmd products del [-h] [--host HOST] [-p PORT] | ||
| [--verbose {info,debug,debug_analyzer}] | ||
| PRODUCT_NAME | ||
| Removes the specified product from the list of products managed by the server. | ||
| NOTE: This only removes the association and disconnects the server from the | ||
| database -- NO actual ANALYSIS DATA is REMOVED. Configuration, such as access | ||
| control, however, WILL BE LOST! | ||
| positional arguments: | ||
| PRODUCT_NAME The URL endpoint where clients can access the analysis | ||
| results for the product. | ||
| optional arguments: | ||
| -h, --help show this help message and exit | ||
| ~~~~~~~~~~~~~~~~~~~~~ |
Oops, something went wrong.