diff --git a/.github/workflows/check_config.yaml b/.github/workflows/check_config.yaml index 6081b97..7f6e0dc 100644 --- a/.github/workflows/check_config.yaml +++ b/.github/workflows/check_config.yaml @@ -20,7 +20,7 @@ jobs: - name: Setup Python uses: actions/setup-python@v2 with: - python-version: 3.7 + python-version: 3.9 - name: Run Checks run: | pip install pyyaml diff --git a/_includes/config.yaml b/_includes/config.yaml index b14c122..65dd20d 100644 --- a/_includes/config.yaml +++ b/_includes/config.yaml @@ -154,6 +154,11 @@ static_root: '/home/inventree/data/static' # Use environment variable INVENTREE_LOGIN_ATTEMPTS #login_attempts: 5 +# Add new user on first startup +#admin_user: admin +#admin_email: info@example.com +#admin_password: inventree + # Permit custom authentication backends #authentication_backends: # - 'django.contrib.auth.backends.ModelBackend' diff --git a/docs/app/connect.md b/docs/app/connect.md index b9c71a3..56c1cb8 100644 --- a/docs/app/connect.md +++ b/docs/app/connect.md @@ -47,7 +47,7 @@ Alternatively, long press on the server profile to activate the context menu, th When the app successfully connects to the server, a success message is briefly displayed at the bottom of the screen. A green icon next to the server profile indicate that the profile is currently *selected* and also the connection was successful. -{% with id="connected", url="app/connected.jpg", maxheight="240px", description="Connected to server" %} +{% with id="connected", url="app/connected.png", maxheight="240px", description="Connected to server" %} {% include 'img.html' %} {% endwith %} @@ -55,7 +55,7 @@ When the app successfully connects to the server, a success message is briefly d If (for whatever reason) the app does not successfully connect to the InvenTree server, a failure message is displayed, and a red icon is displayed next to the server profile. -{% with id="failed", url="app/unauthorized.jpg", maxheight="240px", description="Connection failure" %} +{% with id="failed", url="app/unauthorized.png", maxheight="240px", description="Connection failure" %} {% include 'img.html' %} {% endwith %} @@ -63,7 +63,7 @@ In this case, the error message displayed at the bottom of the screen provides c To edit the server profile details, long press on the server profile, and select *Edit Server Profile*: -{% with id="edit", url="app/edit_server.jpg", maxheight="240px", description="Edit server profile" %} +{% with id="edit", url="app/edit_server.png", maxheight="240px", description="Edit server profile" %} {% include 'img.html' %} {% endwith %} @@ -107,18 +107,6 @@ Select the *Stock* icon to open the [stock display](./stock.md). This initially Select the *Purchase Orders* icon to open the [purchase orders display](./po.md). This shows a list of currently outstanding purchase orders, allowing line items to be received into stock. -### Suppliers - -Select the *Suppliers* icon to display the list of available suppliers - -### Manufacturers - -Select the *Manufacturers* icon to display the list of available manufacturers - -### Customers - -Select the *Customers* icon to display the list of available customers - ### Settings Select the *Settings* icon to open the [settings display](./settings.md) @@ -144,7 +132,7 @@ Select *InvenTree* to navigate to the [home screen](#home-screen). ### Scan Barcode -Select *Scan Barcode* to open the barcode scanner, and scan an InvenTree stock item or location to instantly jump to the relevent view. Refer to the [barcode documentation](./barcode.md) for more information. +Select *Scan Barcode* to open the barcode scanner, and scan an InvenTree stock item or location to instantly jump to the relevant view. Refer to the [barcode documentation](./barcode.md) for more information. ### Search diff --git a/docs/app/issues.md b/docs/app/issues.md index e50fbf3..b312a9e 100644 --- a/docs/app/issues.md +++ b/docs/app/issues.md @@ -4,10 +4,6 @@ title: App Suggestions / Issues ## Suggestions / Issues -To suggest an improvement or new feature for the InvenTree app, or to report an issue, refer to the [InvenTree GitHub page](https://github.com/inventree/inventree/issues). - -Suggestions or issues related to the InvenTree app will be tagged with the `app` label, and can be viewed here: - -[https://github.com/inventree/InvenTree/issues?q=is:open+is:issue+label:app](https://github.com/inventree/InvenTree/issues?q=is%3Aopen+is%3Aissue+label%3Aapp) +To suggest an improvement or new feature for the InvenTree app, or to report an issue, refer to the [InvenTree GitHub page](https://github.com/inventree/inventree-app/issues). General feedback on the app is also welcomed - if you have any ideas on how to make the app more functional or effective, please let us know! \ No newline at end of file diff --git a/docs/app/release.md b/docs/app/release.md deleted file mode 100644 index 3e30524..0000000 --- a/docs/app/release.md +++ /dev/null @@ -1,231 +0,0 @@ ---- -title: App Release Notes ---- - -## InvenTree App Release Notes ---- - -### 0.5.6 - January 2022 ---- - -- Fixes bug related to transferring stock via barcode scanning -- Updated UI for settings -- Adds ability to disable "upload error report" functionality - -### 0.5.5 - January 2022 ---- - -- Fixes bug in stock item creation form - -### 0.5.4 - January 2022 ---- - -- Enable usage of camera flash when scanning barcodes -- Enable camera toggle when scanning barcodes -- Configurable home screen actions -- Updated icon set -- Removed "upload error report" functionality (instead link to GitHub issues) -- Updated multiple language translations - -### 0.5.3 - November 2021 ---- - -- Check for null value when reading user permissions -- Updated Italian language translations -- Updated French language translations - -### 0.5.2 - October 2021 ---- - -- Display error message on HTTPS certificate error - -### 0.5.1 - October 2021 ---- - -- Bug fix for app title - -### 0.5.0 - October 2021 ---- - -- Major UI overhaul -- Adds many more options to the home screen -- Adds global "drawer" - accessible via long-press of the "back" button -- Display Purchase Order details -- Edit Purchase Order information -- Adds ability to receive stock items against purchase orders -- Display Company details (supplier / manufacturer / customer) -- Edit Company information -- Improvements to stock adjustment actions -- Improvements to barcode scanning -- Fixed bug relating to stock transfer for parts with specified "units" -- Multiple other small bug fixes - -### 0.4.7 - September 2021 ---- - -- Display units after stock quantity -- Support multi-byte UTF characters in API transactions -- Updated translations - -### 0.4.6 - August 2021 ---- - -- Improved profile selection screen -- Fixed a number of incorrect labels -- Refactor test result upload functionality -- Refactor file selection and upload functions - -### 0.4.5 - August 2021 ---- - -- Adds ability to create new Part Categories -- Adds ability to create new Parts -- Adds ability to create new Stock Locations -- Adds ability to create new Stock Items -- Adds ability to view and download attachments for Parts -- Adds ability to upload new part attachments -- App bar now always displays "back" button -- Display "batch code" information for stock item -- Display "packaging" information for stock item -- Multiple bug fixes - -### 0.4.3 - August 2021 ---- - -- Multiple bug fixes, mostly related to API calls - -### 0.4.2 - August 2021 ---- - -- Simplify process for uploading part images -- Display total stock "on order" for purchaseable parts -- Display supplier information for purchaseable parts -- Handle error responses from server when scanning barcodes -- Handle error responses from server when fetching model data -- Update translation strings - -### 0.4.1 - July 2021 ---- - -- Null reference bug fix -- Update translations - -### 0.4.0 - July 2021 ---- - -- Fixes bug which prevented opening of external URLs -- Adds ability to edit Part notes -- Adds ability to edit StockItem notes - - -### 0.3.1 - July 2021 ---- - -- Adds new "API driven" forms -- Improvements for Part editing form -- Improvements for PartCategory editing form -- Improvements for StockLocation editing form -- Adds ability to edit StockItem -- Display purchase price (where available) for StockItem -- Updated translations -- Adds support for more languages - -### 0.2.10 - July 2021 ---- - -- Add "last updated" date to StockDetail view -- Add "stocktake" date to StockDetail view -- Display location of stock items in list view - -### 0.2.9 - July 2021 ---- - -- Handle 50x responses from server -- Improved reporting of error messages - -### 0.2.8 - July 2021 ---- - -- Bug fixes for API calls - - -### 0.2.7 - July 2021 ---- - -- Fixed errors in error-handling code - -### 0.2.6 - July 2021 ---- - -- Major code update with "null safety" features -- Handle case of improperly formatted hostname -- Multiple API bug fixes (mostly null references) -- Updated translations - -### 0.2.5 - June 2021 ---- - -- Fixed bug associated with scanning a StockItem into a non-existent location -- Improved error reporting - -### 0.2.4 - June 2021 ---- - -- Upload Part images from phone camera or gallery -- Display error message for improperly formatted server address -- Updated version numbering scheme to match InvenTree server - -### 0.1.5 - May 2021 ---- - -- Added ability for user to submit feedback -- Update translations - -### 0.1.4 - April 2021 ---- - -- Fixes certificate issues connecting to HTTPs server -- Fixes some app crash bugs -- Bug fixes for various API calls -- Improved error messages for invalid user credentials -- UI cleanup - -### 0.1.3 - March 2021 ---- - -- Adds ability to toggle "star" status for Part -- Fixes form display bug for stock adjustment actions -- User permissions are now queried from the InvenTree server -- Any "unauthorized" actions are now not displayed -- Uses server-side pagination, providing a significant increase in UI performance -- Adds audio feedback for server errors and barcode scanning -- Adds "app settings" view - -### 0.1.2 - February 2021 ---- - -- Fixes bug which caused blank screen when opening barcode scanner - -### 0.1.1 - February 2021 ---- - -- Fixes crash bug on top-level part category -- Fixed crash bug on top-level stock location -- Adds context overlay to barcode scanner view -- Notifications are less obtrusive (uses snack bar) -- Fixed search views - keyboard search button now works properly - -### 0.1.0 - February 2021 ---- -This is the initial release of the InvenTree app. - -Available features as described below: - -- Initial app version release -- Navigate through Part tree -- Edit Parts -- Navigate through Stock tree -- Search for Part(s) -- Scan barcode to redirect to various views -- Use barcode scanner to perform various stock actions -- Manage multiple user / server profiles diff --git a/docs/app/settings.md b/docs/app/settings.md index 723c604..03537c2 100644 --- a/docs/app/settings.md +++ b/docs/app/settings.md @@ -9,11 +9,18 @@ The *Settings* view provides access to user configurable settings, in addition t The main settings view is shown below, and provides the following options: - **Server** - Configure and select server profile +- **Home Screen** - Configure home screen settings - **App Settings** - Configure app settings -- **About** - Information about the InvenTree app -- **Documentation** - Opens the InvenTree documentation in an external browser -{% with id="settings_view", url="app/settings.jpg", maxheight="240px", description="Settings view" %} +{% with id="settings_view", url="app/settings.png", maxheight="240px", description="Settings view" %} +{% include 'img.html' %} +{% endwith %} + +## Home Screen + +The *Home Screen* view allows you to configure display options for the app 'home screen': + +{% with id="home_settings", url="app/home_settings.png", maxheight="240px", description="Home Screen Settings" %} {% include 'img.html' %} {% endwith %} @@ -21,10 +28,23 @@ The main settings view is shown below, and provides the following options: The *App Settings* view provides configuration options for the InvenTree app: -{% with id="app_settings", url="app/app_settings.jpg", maxheight="240px", description="App Settings" %} +{% with id="app_settings", url="app/app_settings.png", maxheight="240px", description="App Settings" %} {% include 'img.html' %} {% endwith %} +### Parts + +Configure options for "parts" display: + +- **Include Subcategories** - When viewing a list of parts in a category, include parts from subcategories + +### Stock + +Configure options for "stock" display: + +- **Include Sublocations** - When viewing a list of stock items in a location, include items from sublocations +- **Stock History** - Display stock item history in the stock detail view + ### Sounds Configure audible app notifications: @@ -32,23 +52,7 @@ Configure audible app notifications: - **Server Error** - Play an audible tone when a server error occurs - **Barcode Tones** - Play audible tones when scanning barcodes -## About +### App Settings -The *About* view provides details about the app itself: - -{% with id="about_app", url="app/about.jpg", maxheight="240px", description="About the InvenTree app" %} -{% include 'img.html' %} -{% endwith %} - -### Server Details - -- **Address** - URL of the currently connected server -- **Version** - Version of InvenTree software running on the server -- **Server Instance** - Instance name of the server - -### App Details - -- **Package Name** - Package identifier for the compiled app -- **Version** - App software version -- **Release Notes** - Select to view app release notes -- **Credits** - Select to view additional app credits +- **Use Strict HTTPS** - Enforce strict checking of HTTPs certificates. Enabling this option may prevent you from connecting to the server if there are certificate issues +- **Upload Error Reports** - Enable uploading of anonymous error / crash reports. These reports are used to improve the quality of the app. \ No newline at end of file diff --git a/docs/app/stock.md b/docs/app/stock.md index 77c5791..67738e3 100644 --- a/docs/app/stock.md +++ b/docs/app/stock.md @@ -150,6 +150,18 @@ Select the *assign barcode* action to scan this third-party barcode and assign i This barcode can then be used to track the stock item. +#### Print Label + +If the server supports [label printing plugins](../extend/plugins/label.md), then an option to print a label for the selected stock item: + +{% with id="label_print_1", url="app/stock_print_label_1.png", description="Print label via plugin" %} +{% include 'app_img.html' %} +{% endwith %} + +{% with id="label_print_2", url="app/stock_print_label_2", description="Print label via plugin" %} +{% include 'app_img.html' %} +{% endwith %} + ### Edit Stock Item To edit the stock item details, select the *Edit* button in the top right corner of the screen: diff --git a/docs/assets/images/app/about.jpg b/docs/assets/images/app/about.jpg deleted file mode 100644 index 82fdfac..0000000 Binary files a/docs/assets/images/app/about.jpg and /dev/null differ diff --git a/docs/assets/images/app/add_server_profile.png b/docs/assets/images/app/add_server_profile.png index 9bce796..21d48f3 100644 Binary files a/docs/assets/images/app/add_server_profile.png and b/docs/assets/images/app/add_server_profile.png differ diff --git a/docs/assets/images/app/app_settings.jpg b/docs/assets/images/app/app_settings.jpg deleted file mode 100644 index 18acd57..0000000 Binary files a/docs/assets/images/app/app_settings.jpg and /dev/null differ diff --git a/docs/assets/images/app/app_settings.png b/docs/assets/images/app/app_settings.png new file mode 100644 index 0000000..652ef6a Binary files /dev/null and b/docs/assets/images/app/app_settings.png differ diff --git a/docs/assets/images/app/connected.jpg b/docs/assets/images/app/connected.jpg deleted file mode 100644 index 52675ad..0000000 Binary files a/docs/assets/images/app/connected.jpg and /dev/null differ diff --git a/docs/assets/images/app/connected.png b/docs/assets/images/app/connected.png new file mode 100644 index 0000000..689a123 Binary files /dev/null and b/docs/assets/images/app/connected.png differ diff --git a/docs/assets/images/app/edit_server.jpg b/docs/assets/images/app/edit_server.jpg deleted file mode 100644 index 925bdc6..0000000 Binary files a/docs/assets/images/app/edit_server.jpg and /dev/null differ diff --git a/docs/assets/images/app/edit_server.png b/docs/assets/images/app/edit_server.png new file mode 100644 index 0000000..8b8e21f Binary files /dev/null and b/docs/assets/images/app/edit_server.png differ diff --git a/docs/assets/images/app/home.png b/docs/assets/images/app/home.png index 5c06227..0a72fdd 100644 Binary files a/docs/assets/images/app/home.png and b/docs/assets/images/app/home.png differ diff --git a/docs/assets/images/app/home_settings.png b/docs/assets/images/app/home_settings.png new file mode 100644 index 0000000..b25a596 Binary files /dev/null and b/docs/assets/images/app/home_settings.png differ diff --git a/docs/assets/images/app/initial.png b/docs/assets/images/app/initial.png index bfa4c04..851e83a 100644 Binary files a/docs/assets/images/app/initial.png and b/docs/assets/images/app/initial.png differ diff --git a/docs/assets/images/app/search_1.png b/docs/assets/images/app/search_1.png index ea2926c..d24d7d9 100644 Binary files a/docs/assets/images/app/search_1.png and b/docs/assets/images/app/search_1.png differ diff --git a/docs/assets/images/app/search_2.png b/docs/assets/images/app/search_2.png index c7465e2..61479ab 100644 Binary files a/docs/assets/images/app/search_2.png and b/docs/assets/images/app/search_2.png differ diff --git a/docs/assets/images/app/settings.jpg b/docs/assets/images/app/settings.jpg deleted file mode 100644 index c93fd9c..0000000 Binary files a/docs/assets/images/app/settings.jpg and /dev/null differ diff --git a/docs/assets/images/app/settings.png b/docs/assets/images/app/settings.png new file mode 100644 index 0000000..60fb110 Binary files /dev/null and b/docs/assets/images/app/settings.png differ diff --git a/docs/assets/images/app/stock_print_label_1.png b/docs/assets/images/app/stock_print_label_1.png new file mode 100644 index 0000000..ae7e9ae Binary files /dev/null and b/docs/assets/images/app/stock_print_label_1.png differ diff --git a/docs/assets/images/app/stock_print_label_2.png b/docs/assets/images/app/stock_print_label_2.png new file mode 100644 index 0000000..981f9ec Binary files /dev/null and b/docs/assets/images/app/stock_print_label_2.png differ diff --git a/docs/assets/images/app/unauthorized.jpg b/docs/assets/images/app/unauthorized.jpg deleted file mode 100644 index 66eb999..0000000 Binary files a/docs/assets/images/app/unauthorized.jpg and /dev/null differ diff --git a/docs/assets/images/app/unauthorized.png b/docs/assets/images/app/unauthorized.png new file mode 100644 index 0000000..5e854c8 Binary files /dev/null and b/docs/assets/images/app/unauthorized.png differ diff --git a/docs/assets/images/appgallery/screen_1.png b/docs/assets/images/appgallery/screen_1.png index 5c06227..56f438b 100644 Binary files a/docs/assets/images/appgallery/screen_1.png and b/docs/assets/images/appgallery/screen_1.png differ diff --git a/docs/assets/images/appgallery/screen_15.png b/docs/assets/images/appgallery/screen_15.png new file mode 100644 index 0000000..9c7f039 Binary files /dev/null and b/docs/assets/images/appgallery/screen_15.png differ diff --git a/docs/assets/images/build/auto_allocate_dialog.png b/docs/assets/images/build/auto_allocate_dialog.png new file mode 100644 index 0000000..66c8775 Binary files /dev/null and b/docs/assets/images/build/auto_allocate_dialog.png differ diff --git a/docs/assets/images/buy/supplier_part_availability.png b/docs/assets/images/buy/supplier_part_availability.png new file mode 100644 index 0000000..56a2196 Binary files /dev/null and b/docs/assets/images/buy/supplier_part_availability.png differ diff --git a/docs/assets/images/buy/update_availability.png b/docs/assets/images/buy/update_availability.png new file mode 100644 index 0000000..54836c9 Binary files /dev/null and b/docs/assets/images/buy/update_availability.png differ diff --git a/docs/assets/images/part/scheduling.png b/docs/assets/images/part/scheduling.png new file mode 100644 index 0000000..ed3c762 Binary files /dev/null and b/docs/assets/images/part/scheduling.png differ diff --git a/docs/assets/images/plugin/app_locate.png b/docs/assets/images/plugin/app_locate.png new file mode 100644 index 0000000..019dd31 Binary files /dev/null and b/docs/assets/images/plugin/app_locate.png differ diff --git a/docs/assets/images/plugin/panels.png b/docs/assets/images/plugin/panels.png new file mode 100644 index 0000000..a16d6b0 Binary files /dev/null and b/docs/assets/images/plugin/panels.png differ diff --git a/docs/assets/images/plugin/print_label_select_plugin.png b/docs/assets/images/plugin/print_label_select_plugin.png new file mode 100644 index 0000000..f09fd8b Binary files /dev/null and b/docs/assets/images/plugin/print_label_select_plugin.png differ diff --git a/docs/assets/images/plugin/web_locate.png b/docs/assets/images/plugin/web_locate.png new file mode 100644 index 0000000..aba240a Binary files /dev/null and b/docs/assets/images/plugin/web_locate.png differ diff --git a/docs/assets/images/report/bom_example.png b/docs/assets/images/report/bom_example.png new file mode 100644 index 0000000..a674631 Binary files /dev/null and b/docs/assets/images/report/bom_example.png differ diff --git a/docs/assets/images/sell/complete_shipment.png b/docs/assets/images/sell/complete_shipment.png new file mode 100644 index 0000000..f94341f Binary files /dev/null and b/docs/assets/images/sell/complete_shipment.png differ diff --git a/docs/assets/images/sell/complete_shipment_action.png b/docs/assets/images/sell/complete_shipment_action.png new file mode 100644 index 0000000..989c3e3 Binary files /dev/null and b/docs/assets/images/sell/complete_shipment_action.png differ diff --git a/docs/assets/images/sell/completed_shipments.png b/docs/assets/images/sell/completed_shipments.png new file mode 100644 index 0000000..4a1f7db Binary files /dev/null and b/docs/assets/images/sell/completed_shipments.png differ diff --git a/docs/assets/images/sell/edit_shipment.png b/docs/assets/images/sell/edit_shipment.png new file mode 100644 index 0000000..693dfde Binary files /dev/null and b/docs/assets/images/sell/edit_shipment.png differ diff --git a/docs/assets/images/sell/pending_shipments.png b/docs/assets/images/sell/pending_shipments.png new file mode 100644 index 0000000..80d0a10 Binary files /dev/null and b/docs/assets/images/sell/pending_shipments.png differ diff --git a/docs/build/allocate.md b/docs/build/allocate.md index 1cad5ac..d98494c 100644 --- a/docs/build/allocate.md +++ b/docs/build/allocate.md @@ -61,25 +61,20 @@ In each row, pressing the icon expands the row {% include "img.html" %} {% endwith %} -### Auto Allocation - -To speed up the allocation process, the *Auto Allocate* button can be used to allocate untracked stock items to the build. Automatic allocation of stock items does not work in every situation, as a number of criteria must be met. +## Manual Stock Allocation For each line in the BOM, stock will be automatically allocated if one (and only one) stock item (for the referenced part) is found (within the specified *source location* for the build): -!!! warning "Multiple Stock Items" - If multiple stock items are available, the InvenTree auto allocation system cannot make a determination about which stock item to allocate. - -Selecting *Auto Allocate* opens a dialog window which displays the stock items which will be allocated to the build during the auto allocation process: +Selecting *Allocate Stock* opens a dialog window which displays the stock items which will be allocated to the build during the auto allocation process: {% with id="build_auto", url="build/build_auto_allocate.png", description="Auto allocate" %} {% include "img.html" %} {% endwith %} -!!! info "Note" - Note here that the *SAM-M8Q-0-10* part can be automatically allocated as it only exists in a single stock location. However the other BOM line item exists in multiple locations, and thus cannot be automatically allocated +Note here that there are two parts in the BOM which can be automatically allocated, as they only have a single corresponding StockItem available. +However the other BOM line item exists in multiple locations, and thus cannot be automatically allocated. These will need to be manually selected by the user. -### Manual Allocation +### Row Allocation Stock can be manually allocated to the build as required, using the *Allocate stock* button available in each row of the allocation table @@ -91,6 +86,34 @@ Stock allocations can be manually adjusted or deleted using the action buttons a The *Unallocate Stock* button can be used to remove all allocations of untracked stock items against the build order. +## Automatic Stock Allocation + +To speed up the allocation process, the *Auto Allocate* button can be used to allocate untracked stock items to the build. Automatic allocation of stock items does not work in every situation, as a number of criteria must be met. + +The *Automatic Allocation* dialog is presented as shown below: + +{% with id="auto_allocate_dialog", url="build/auto_allocate_dialog.png", description="Automatic allocation dialog" %} +{% include "img.html" %} +{% endwith %} + +**Source Location** + +Select the master location where stock items are to be allocated from. Leave this input blank to allocate stock items from any available location. + +**Interchangeable Stock** + +Set this option to *True* to signal that stock items can be used interchangeably. This means that in the case where multiple stock items are available, the auto-allocation routine does not care which stock item it uses. + +!!! warning "Take Care" + If the *Interchangeable Stock* option is enabled, and there are multiple stock items available, the results of the automatic allocation algorithm may somewhat unexpected. + +!!! info "Example" + Let's say that we have 5 reels of our *C_100nF_0603* capacitor, each with 4,000 parts available. If we do not mind which of these reels the stock should be taken from, we enable the *Interchangeable Stock* option in the dialog above. In this case, the stock will be allocated from one of these reels, and eventually subtracted from stock when the build is completed. + +**Substitute Stock** + +Set this option to *True* to allow substitute parts (as specifed by the BOM) to be allocated, if the primary parts are not available. + ## Allocating Tracked Stock Allocation of tracked stock items is slightly more complex. Instead of being allocated against the *Build Order*, tracked stock items must be allocated against an individual *Build Output*. diff --git a/docs/companies/manufacturer.md b/docs/buy/manufacturer.md similarity index 100% rename from docs/companies/manufacturer.md rename to docs/buy/manufacturer.md diff --git a/docs/companies/po.md b/docs/buy/po.md similarity index 100% rename from docs/companies/po.md rename to docs/buy/po.md diff --git a/docs/companies/supplier.md b/docs/buy/supplier.md similarity index 83% rename from docs/companies/supplier.md rename to docs/buy/supplier.md index 9d445ff..29cc960 100644 --- a/docs/companies/supplier.md +++ b/docs/buy/supplier.md @@ -65,3 +65,21 @@ After the supplier part details are loaded, click on the icon next to the supplier part image. Review the the information for the supplier part to be deleted, confirm the deletion using the checkbox then click on Submit + +### Supplier Part Availability + +InvenTree supports tracking 'availability' information for supplier parts. While this information can be updated manually, it is more useful when used in conjunction with the InvenTree plugin system. + +A custom can periodically request availability information (via a supplier API), and update this availability information for each supplier part. + +If provided, availability information is displayed on the Supplier Part detail page. + +{% with id="supplier_part_availability", url="buy/supplier_part_availability.png", maxheight="240px", description="Supplier part availability" %} +{% include "img.html" %} +{% endwith %} + +Availability information can be manually updated via the user interface: + +{% with id="update_availability", url="buy/update_availability.png", maxheight="240px", description="Update availability" %} +{% include "img.html" %} +{% endwith %} \ No newline at end of file diff --git a/docs/credits.md b/docs/credits.md index ff4417a..90bf30a 100644 --- a/docs/credits.md +++ b/docs/credits.md @@ -62,6 +62,7 @@ InvenTree relies on the following frontend libraries and components: | [Moment JS](https://github.com/moment/momentjs.com/) | MIT | Time and date rendering | | [jquery-treegrid](https://github.com/maxazan/jquery-treegrid/) | MIT | Treegrid rendering | | [clipboard.js](https://github.com/zenorocha/clipboard.js) | MIT | text copying | +| [qr-scanner](https://github.com/nimiq/qr-scanner) | MIT | Javascript QR Code Scanner | ## Source Code Contributions diff --git a/docs/extend/how_to_plugin.md b/docs/extend/how_to_plugin.md index d2a9fc8..3ce0e7b 100644 --- a/docs/extend/how_to_plugin.md +++ b/docs/extend/how_to_plugin.md @@ -36,32 +36,61 @@ If you want to make your life easier, try to follow these guidelines; break wher - keep it simple - more that 1000 LOC are normally to much for a plugin - use mixins where possible - we try to keep coverage high for them so they are not likely to break - do not use internal functions - if a functions name starts with `_` it is internal and might change at any time -- keep you imports clean - the APIs for plugins and mixins are young and evolving. Use +- keep you imports clean - the APIs for plugins and mixins are young and evolving (see [here](plugins.md#imports)). Use ``` -from plugin import IntegrationPluginBase, registry +from plugin import InvenTreePlugin, registry from plugin.mixins import APICallMixin, SettingsMixin, ScheduleMixin, BarcodeMixin ``` -- deliver as a package - pip is great for dependency management and pypi can serve as a transparent and reliable delivery infrastructure +- deliver as a package (see [below](#packaging)) - if you need to use a private infrastructure, use the 'Releases' functions in GitHub or Gitlab. Point to the 'latest' release endpoint when installing to make sure the update function works -- tag your GitHub repo with 'inventree' and 'inventreeplugins' to make discovery easier +- tag your GitHub repo with `inventree` and `inventreeplugins` to make discovery easier. A discovery mechanism using these tags is on the roadmap. - use GitHub actions to test your plugin regularly (you can [schedule actions](https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows#schedule)) against the 'latest' [docker-build](https://hub.docker.com/r/inventree/inventree) of InvenTree - if you use the AppMixin pin your plugin against the stable branch of InvenTree, your migrations might get messed up otherwise +### Packaging + +The recommended way of distribution is as a [PEP 561](https://peps.python.org/pep-0561/) compliant package. If you can use the official Package Index (PyPi - [official website](https://pypi.org/)) as a registry. +Please follow PyPAs official [packaging guide](https://packaging.python.org/en/latest/tutorials/packaging-projects/) to ensure your package installs correctly suing InvenTrees install mechanisms. + +Your package must expose you plugin class as an [entrypoint](https://setuptools.pypa.io/en/latest/userguide/entry_point.html) with the name `inventree_plugins` to work with InvenTree. + +```setup.cfg +# Example setup.cfg +[options.entry_points] +inventree_plugins = + ShopifyIntegrationPlugin = path.to.source:ShopifyIntegrationPluginClass +``` + +```setup.py +# Example setup.py + +import setuptools + +# ... + +setuptools.setup( + name='ShopifyIntegrationPlugin' + .# .. + + entry_points={"inventree_plugins": ["ShopifyIntegrationPlugin = path.to.source:ShopifyIntegrationPluginClass"]} +``` + + ### A simple example This example adds a new action under `/api/action/sample` using the ActionMixin. ``` py # -*- coding: utf-8 -*- """sample implementation for ActionPlugin""" -from plugin import IntegrationPluginBase +from plugin import InvenTreePlugin from plugin.mixins import ActionMixin -class SampleActionPlugin(ActionMixin, IntegrationPluginBase): +class SampleActionPlugin(ActionMixin, InvenTreePlugin): """ Use docstrings for everything... pls """ - PLUGIN_NAME = "SampleActionPlugin" + NAME = "SampleActionPlugin" ACTION_NAME = "sample" # metadata diff --git a/docs/extend/integrate.md b/docs/extend/integrate.md index bc2e825..72ef395 100644 --- a/docs/extend/integrate.md +++ b/docs/extend/integrate.md @@ -18,3 +18,8 @@ A list of known third-party InvenTree extensions is provided below. If you have [F360-InvenTree](https://github.com/matmair/F360-InvenTree/) is a tool for creating links between Autodesk Fusion 360 components and InvenTree parts. Still under heavy development. + +### DigitalOcean droplet + +[InvenTree droplet](https://marketplace.digitalocean.com/apps/inventree?refcode=d6172576d014) is a 1-click solution to deploy InvenTree in the cloud with DigitalOcean. You still have to administer and update your instance. +The source code for this droplet can be found in [inventree_droplet](https://github.com/invenhost/inventree_droplet). diff --git a/docs/extend/plugins.md b/docs/extend/plugins.md index 1cdcd23..b2d4958 100644 --- a/docs/extend/plugins.md +++ b/docs/extend/plugins.md @@ -7,26 +7,67 @@ title: Plugins The InvenTree server code supports an extensible plugin architecture, allowing custom plugins to be integrated directly into the database server. This allows development of complex behaviours which are decoupled from core InvenTree code. Plugins can be added from multiple sources: -- InvenTree built-in plugins are located in the directory `./InvenTree/plugin/builtin`. -- Custom plugins should be placed in the directory `./InvenTree/plugins`. -- Plugins can be installed via PIP (python package manager) -Plugins are discovered and loaded when the server is started. +- Plugins can be installed via PIP (python package manager) +- Custom plugins should be placed in the directory `./InvenTree/plugins`. +- InvenTree built-in plugins are located in the directory `./InvenTree/plugin/builtin`. + +Note: Plugins are discovered and loaded only when the server is started. !!! info "Enable Plugin Support" To enable custom plugins, plugin support must be activated in the [server configuration](../start/config.md). +!!! question "Have you tried turning it off and on again?" + When new plugins are installed (and activated), both the web server and background worker must be restarted. + ### Plugin Base Class -Custom plugins must inherit from the [IntegrationPluginBase class](https://github.com/inventree/InvenTree/blob/master/InvenTree/plugin/integration.py). Any plugins installed via the methods outlined above will be "discovered" when the InvenTree server launches. +Custom plugins must inherit from the [InvenTreePlugin class](https://github.com/inventree/InvenTree/blob/2d1776a151721d65d0ae007049d358085b2fcfd5/InvenTree/plugin/plugin.py#L204). Any plugins installed via the methods outlined above will be "discovered" when the InvenTree server launches. + +!!! warning "Namechange" + The name of the base class was changed with `0.7.0` from `IntegrationPluginBase` to `InvenTreePlugin`. While the old name is still available till `0.8.0` we strongly suggest upgrading your plugins. Deprecation warnings are raised if the old name is used. + +### Imports + +As the code base is evolving import paths might change. Therefore we provide stable import targets for important python APIs. +Please read all release notes and watch out for warnings - we generally provide backports for depreciated interfaces for at least one minor release. + +#### Plugins + +Generall classes an mechanisms are provided under the `plugin` [namespaces](https://github.com/inventree/InvenTree/blob/master/InvenTree/plugin/__init__.py). These include: + +```python +# Management objects +registry # Object that manages all plugin states and integrations + +# Base classes +InvenTreePlugin # Base class for all plugins + +# Errors +MixinImplementationError # Is raised if a mixin is implemented wrong (default not overwritten for example) +MixinNotImplementedError # Is raised if a mixin was not implemented (core mechanisms are missing from the plugin) +``` + +#### Mixins + +Mixins are split up internally to keep the source tree clean and enable better testing seperation. All public APIs that should be used are exposed under `plugin.mixins`. These include all built-in mixins and notification methods. An up-to-date reference can be found in the source code (current master can be [found here](https://github.com/inventree/InvenTree/blob/master/InvenTree/plugin/mixins/__init__.py)). + +#### Models and other internal InvenTree APIs + +!!! warning "Danger Zone" + The APIs outside of the `plugin` namespace are not structured for public usage and require a more in-depth knowledge of the Django framework. Please ask in GitHub discussions of the `ÌnvenTree` org if you are not sure you are using something the intended way. + +We do not provide stable interfaces to models or any other internal python APIs. If you need to integrate into these parts please make yourself familiar with the codebase. We follow general Django patterns and only stray from them in limited, special cases. +If you need to react to state changes please use the [EventMixin](./plugins/event.md). ### Plugin Options -Some metadata options can be defined as constants in the plugins class +Some metadata options can be defined as constants in the plugins class. ``` python -PLUGIN_SLUG = None # Used in URLs, setting-names etc. when a unique slug as a reference is needed -> the plugin name is used if not set -PLUGIN_TITLE = None # A nice human friendly name for the plugin -> used in titles, as plugin name etc. +NAME = '' # Used as a general reference to the plugin +SLUG = None # Used in URLs, setting-names etc. when a unique slug as a reference is needed -> the plugin name is used if not set +TITLE = None # A nice human friendly name for the plugin -> used in titles, as plugin name etc. AUTHOR = None # Author of the plugin, git commit information is used if not present PUBLISH_DATE = None # Publishing date of the plugin, git commit information is used if not present @@ -43,11 +84,11 @@ A *PluginConfig* database entry will be created for each plugin "discovered" whe The configuration entries must be enabled via the [InvenTree admin interface](../settings/admin.md). !!! warning "Disabled by Default" - Newly discovered plugins are disabled by default, and must be manually enabled by an admin user + Newly discovered plugins are disabled by default, and must be manually enabled (in the admin interface) by a user with staff privileges. ### Plugin Mixins -Common use cases are covered by pre-supplied modules in the form of mixins (similar to how [django](https://docs.djangoproject.com/en/stable/topics/class-based-views/mixins/) does it). Each mixin enables the integration into a specific area of InvenTree. Sometimes it also enhances the plugin with helper functions to supply often used functions out-of-the-box. +Common use cases are covered by pre-supplied modules in the form of *mixins* (similar to how [django](https://docs.djangoproject.com/en/stable/topics/class-based-views/mixins/) does it). Each mixin enables the integration into a specific area of InvenTree. Sometimes it also enhances the plugin with helper functions to supply often used functions out-of-the-box. Supported mixin classes are: @@ -56,7 +97,10 @@ Supported mixin classes are: - [AppMixin](./plugins/app.md) - [BarcodeMixin](./plugins/barcode.md) - [EventMixin](./plugins/event.md) +- [LabelPrintingMixin](./plugins/label.md) +- [LocateMixin](./plugins/locate.md) - [NavigationMixin](./plugins/navigation.md) +- [PanelMixin](./plugins/panel.md) - [ScheduleMixin](./plugins/schedule.md) - [SettingsMixin](./plugins/settings.md) - [UrlsMixin](./plugins/urls.md) @@ -65,10 +109,20 @@ Supported mixin classes are: Plugins can either be loaded from paths in the InvenTree install directory or as a plugin installed via pip. We recommend installation via pip as this enables hassle-free upgrades. -For development new plugins can be placed ina a subdirectory in `src/InvenTree/plugins`. Built-In plugins ship in `src/InvenTree/plugin/builtin`. To achive full unit-testing for all mixins there are some sample implementations in `src/InvenTree/plugin/samples`. These are not loaded in production mode. +### Builtin Plugins -### Plugin Installation File +Built-In plugins ship in `src/InvenTree/plugin/builtin`. To achive full unit-testing for all mixins there are some sample implementations in `src/InvenTree/plugin/samples`. These are not loaded in production mode. + +### Local Directory + +Custom plugins can be placed in the `src/InvenTree/plugins/` directory, where they will be automatically discovered. This can be useful for developing and testing plugins, but can prove more difficult in production (e.g. when using Docker). + +### Plugin Installation File (PIP) Plugins installation can be simplified by providing a list of plugins in a plugin configuration file. This file (by default, 'plugins.txt' in the same directory as the server configuration file) contains a list of required plugin packages. -Plugins can be installed from this file by simply running the command `invoke plugins`. +Plugins can be then installed from this file by simply running the command `invoke plugins`. + +!!! success "Auto Update" + When the server installation is updated via the `invoke update` command, the plugins (as specified in *plugins.txt*) will also be updated automatically. + diff --git a/docs/extend/plugins/event.md b/docs/extend/plugins/event.md index 5dbf92d..61a1852 100644 --- a/docs/extend/plugins/event.md +++ b/docs/extend/plugins/event.md @@ -11,7 +11,7 @@ When a certain (server-side) event occurs, the background worker passes the even Implementing classes must provide a `process_event` function: ```python -class EventPlugin(EventMixin, IntegrationPluginBase): +class EventPlugin(EventMixin, InvenTreePlugin): """ A simple example plugin which responds to events on the InvenTree server. @@ -19,9 +19,9 @@ class EventPlugin(EventMixin, IntegrationPluginBase): A more complex plugin could respond to specific events however it wanted. """ - PLUGIN_NAME = "EventPlugin" - PLUGIN_SLUG = "event" - PLUGIN_TITLE = "Triggered Events" + NAME = "EventPlugin" + SLUG = "event" + TITLE = "Triggered Events" def process_event(self, event, *args, **kwargs): print(f"Processing triggered event: '{event}'") diff --git a/docs/extend/plugins/integration.md b/docs/extend/plugins/integration.md deleted file mode 100644 index e247ee1..0000000 --- a/docs/extend/plugins/integration.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: Integration Plugins ---- - -### Integration Plugins - -Integration Plugins provide a wide area of deep integration into the interface of InvenTree. - -For an example of a pretty much full Integration Plugin, refer to `/InvenTree/plugin/samples/integration/sample.py` - -#### Plugin Options - -Some metadata options can be defined as constants in the plugins class. - -``` python -PLUGIN_SLUG = None # Used in URLs, setting-names etc. when a unique slug as a reference is needed -> the plugin name is used if not set -PLUGIN_TITLE = None # A nice human friendly name for the plugin -> used in titles, as plugin name etc. - -AUTHOR = None # Author of the plugin, git commit information is used if not present -PUBLISH_DATE = None # Publishing date of the plugin, git commit information is used if not present -VERSION = None # Version of the plugin -WEBSITE = None # Website for the plugin, developer etc. -> is shown in plugin overview if set -``` - - - -## -#### Mixins - -Common use cases are covered by pre-supplied modules in the form of mixins (similar to how [django](https://docs.djangoproject.com/en/stable/topics/class-based-views/mixins/) does it). Each mixin enables the integration into a specific area of InvenTree. Sometimes it also enhances the plugin with helper functions to supply often used functions out-of-the-box. - -##### Basic Mixin Functions - -All mixins are registered with the plugin on start-up so you can access all added mixins as a dict with the `plugin.registered_mixins` property that is added to each plugin. - -The function `plugin.mixin_enabled(key)` returns if a mixin is present in a plugin and configured correctly. - -##### Initialisation - -Each mixin must call `super().__init__()` in it's `__init__` function and register itself with a call to `self.add_mixin()`. Check out the built-in mixins for examples. - -``` python -def __init__(self): - super().__init__() - self.add_mixin('settings', 'has_settings', __class__) -``` - -##### Meta Options - -Each mixin can define additional options as a Meta subclass. These are used to describe the mixin. - - -#### SettingsMixin - -Use the class constant `SETTINGS` for a dict of settings that should be added as global database settings. -The dict must be formatted similar to the following sample. Take a look at the settings defined in `InvenTree.common.models.InvenTreeSetting` for all possible parameters. - - -``` python -SETTINGS = { - 'PO_FUNCTION_ENABLE': { - 'name': _('Enable PO'), - 'description': _('Enable PO functionality in InvenTree interface'), - 'default': True, - 'validator': bool, - }, -} -``` - -!!! note "Use carefully" - All global and user settings are exposed to the frontend code and can be read out via the browsers developer tools. You can protect a setting from export by adding `'protected': True` to sensitive settings. - You can access settings in frontend JS code under the global variable `global_settings`. - -This mixin defines the helper functions `plugin.get_setting` and `plugin.set_seting` to access all plugin specific settings. - - -#### UrlsMixin - -Use the class constant `URLS` for a array of URLs that should be added to InvenTrees URL paths or override the `plugin.setup_urls` function. -The array has to contain valid URL patterns as defined in the [django documentation](https://docs.djangoproject.com/en/stable/topics/http/urls/). - -``` python -URLS = [ - url(r'increase/(?P\d+)/(?P\d+)/', self.view_increase, name='increase-level'), -] -``` - -The URLs get exposed under `/plugin/{plugin.slug}/*` and get exposed to the template engine with the prefix `plugin:{plugin.slug}:` (for usage with the [url tag](https://docs.djangoproject.com/en/stable/ref/templates/builtins/#url)). - - -#### NavigationMixin - -Use the class constant `NAVIGATION` for a array of links that should be added to InvenTrees navigation header. -The array must contain at least one dict that at least define a name and a link for each element. The link must be formatted for a URL pattern name lookup - links to external sites are not possible directly. The optional icon must be a class reference to an icon (InvenTree ships with fontawesome 4 by default). - -``` python -NAVIGATION = [ - {'name': 'SampleIntegration', 'link': 'plugin:sample:hi', 'icon': 'fas fa-box'}, -] -``` - -The optional class constants `NAVIGATION_TAB_NAME` and `NAVIGATION_TAB_ICON` can be used to change the name and icon for the parent navigation node. - - -#### AppMixin - -If this mixin is added to a plugin the directory the plugin class is defined in is added to InvenTrees `INSTALLED_APPS`. - -!!! warning "Danger Zone" - Only use this mixin if you have an understanding of djangos [app system](https://docs.djangoproject.com/en/stable/ref/applications). Plugins with this mixin are deeply integrated into InvenTree and can cause difficult to reproduce or long-running errors. Use the built-in testing functions of django to make sure your code does not cause unwanted behaviour in InvenTree before releasing. diff --git a/docs/extend/plugins/label.md b/docs/extend/plugins/label.md new file mode 100644 index 0000000..ecbacbd --- /dev/null +++ b/docs/extend/plugins/label.md @@ -0,0 +1,55 @@ +--- +title: Label Mixin +--- + +## LabelPrintingMixin + +The `LabelPrintingMixin` class enables plugins to print labels directly to a connected printer. Custom plugins can be written to support any printer backend. + +An example of this is the [inventree-brother-plugin](https://github.com/inventree/inventree-brother-plugin) which provides native support for the Brother QL and PT series of networked label printers. + +### Web Integration + +If label printing plugins are enabled, they are able to be used directly from the InvenTree web interface: + +{% with id="label_print", url="plugin/print_label_select_plugin.png", description="Print label via plugin" %} +{% include 'img.html' %} +{% endwith %} + +### App Integration + +Label printing plugins also allow direct printing of labels via the [mobile app](../../app/stock.md#print-label) + +## Implementation + +Plugins which implement the `LabelPrintingMixin` mixin class must provide a `print_label` function: + +```python +from dummy_printer import printer_backend + +class MyLabelPrinter(LabelPrintingMixin, InvenTreePlugin): + """ + A simple example plugin which provides support for a dummy printer. + + A more complex plugin would communicate with an actual printer! + """ + + NAME = "MyLabelPrinter" + SLUG = "mylabel" + TITLE = "A dummy printer" + + def print_label(self, label, **kwargs): + """ + Send the label to the printer + + Arguments: + label: A PIL (pillow) Image file + """ + + width = kwargs['width'] + height = kwargs['height'] + + printer_backend.print(label, w=width, h=height) +``` + + diff --git a/docs/extend/plugins/locate.md b/docs/extend/plugins/locate.md new file mode 100644 index 0000000..e56f4c0 --- /dev/null +++ b/docs/extend/plugins/locate.md @@ -0,0 +1,31 @@ +--- +title: Locate Mixin +--- + +## LocateMixin + +The `LocateMixin` class enables plugins to "locate" stock items (or stock locations) via an entirely custom method. + +For example, a warehouse could be arranged with each individual 'parts bin' having an audio-visual indicator (e.g. RGB LED and buzzer). "Locating" a particular stock item causes the LED to flash and the buzzer to sound. + +Another example might be a parts retrieval system, where "locating" a stock item causes the stock item to be "delivered" to the user via a conveyor. + +The possibilities are endless! + +### Web Integration + +{% with id="web_locate", url="plugin/web_locate.png", description="Locate stock item from web interface", maxheight="400px" %} +{% include 'img.html' %} +{% endwith %} + +### App Integration + +If a locate plugin is installed and activated, the [InvenTree mobile app](../../app/app.md) displays a button for locating a StockItem or StockLocation (see below): + +{% with id="app_locate", url="plugin/app_locate.png", description="Locate stock item from app", maxheight="400px" %} +{% include 'img.html' %} +{% endwith %} + +### Implementation + +Refer to the [InvenTree source code](https://github.com/inventree/InvenTree/blob/master/InvenTree/plugin/samples/locate/locate_sample.py) for a simple implementation example. diff --git a/docs/extend/plugins/navigation.md b/docs/extend/plugins/navigation.md index 86e3ce4..36c4a6f 100644 --- a/docs/extend/plugins/navigation.md +++ b/docs/extend/plugins/navigation.md @@ -8,9 +8,9 @@ Use the class constant `NAVIGATION` for a array of links that should be added to The array must contain at least one dict that at least define a name and a link for each element. The link must be formatted for a URL pattern name lookup - links to external sites are not possible directly. The optional icon must be a class reference to an icon (InvenTree ships with fontawesome 4 by default). ``` python -class MyNavigationPlugin(NavigationMixin, IntegrationPluginBase): +class MyNavigationPlugin(NavigationMixin, InvenTreePlugin): - PLUGIN_NAME = "NavigationPlugin" + NAME = "NavigationPlugin" NAVIGATION = [ {'name': 'SampleIntegration', 'link': 'plugin:sample:hi', 'icon': 'fas fa-box'}, diff --git a/docs/extend/plugins/panel.md b/docs/extend/plugins/panel.md new file mode 100644 index 0000000..07788a4 --- /dev/null +++ b/docs/extend/plugins/panel.md @@ -0,0 +1,27 @@ +--- +title: Panel Mixin +--- + +## PanelMixin + +The `PanelMixin` enables plugins to render custom content to "panels" on individual pages in the web interface. + +Most pages in the web interface support multiple panels, which are selected via the sidebar menu on the left side of the screen: + +{% with id="panels", url="plugin/panels.png", description="Display panels" %} +{% include 'img.html' %} +{% endwith %} + +Each plugin which implements this mixin can return zero or more custom panels for a particular page. The plugin can decide (at runtime) which panels it wishes to render. This determination can be made based on the page routing, the item being viewed, the particular user, or other considerations. + +### Panel Content + +Panel content can be rendered by returning HTML directly, or by rendering from a template file. + +### Javascript + +Custom code can be provided which will run when the particular panel is first loaded (by selecting it from the side menu). + +## Example Implementation + +Refer to the `CustomPanelSample` example class in the `./plugin/samples/integration/` directory, for a fully worked example of how custom UI panels can be implemented. \ No newline at end of file diff --git a/docs/extend/plugins/schedule.md b/docs/extend/plugins/schedule.md index c4a74e5..a680a15 100644 --- a/docs/extend/plugins/schedule.md +++ b/docs/extend/plugins/schedule.md @@ -16,13 +16,13 @@ The ScheduleMixin class provides a plugin with the ability to call functions at An example of a plugin which supports scheduled tasks: ```python -class ScheduledTaskPlugin(ScheduleMixin, SettingsMixin, IntegrationPluginBase): +class ScheduledTaskPlugin(ScheduleMixin, SettingsMixin, InvenTreePlugin): """ Sample plugin which runs a scheduled task, and provides user configuration. """ - PLUGIN_NAME = "Scheduled Tasks" - PLUGIN_SLUG = 'schedule' + NAME = "Scheduled Tasks" + SLUG = 'schedule' SCHEDULED_TASKS = { 'global': { diff --git a/docs/extend/plugins/settings.md b/docs/extend/plugins/settings.md index 484ed81..8309b77 100644 --- a/docs/extend/plugins/settings.md +++ b/docs/extend/plugins/settings.md @@ -15,9 +15,9 @@ The dict must be formatted similar to the following sample. Take a look at the s ``` python -class PluginWithSettings(SettingsMixin, IntegrationPluginBase): +class PluginWithSettings(SettingsMixin, InvenTreePlugin): - PLUGIN_NAME = "PluginWithSettings" + NAME = "PluginWithSettings" SETTINGS = { 'API_ENABLE': { diff --git a/docs/extend/plugins/urls.md b/docs/extend/plugins/urls.md index 1892a94..e242e7a 100644 --- a/docs/extend/plugins/urls.md +++ b/docs/extend/plugins/urls.md @@ -9,9 +9,9 @@ Use the class constant `URLS` for a array of URLs that should be added to InvenT The array has to contain valid URL patterns as defined in the [django documentation](https://docs.djangoproject.com/en/stable/topics/http/urls/). ``` python -class MyUrlsPlugin(URLsMixin, IntegrationPluginBase): +class MyUrlsPlugin(URLsMixin, InvenTreePlugin): - PLUGIN_NAME = "UrlsMixin" + NAME = "UrlsMixin" URLS = [ url(r'increase/(?P\d+)/(?P\d+)/', self.view_increase, name='increase-level'), diff --git a/docs/extend/python.md b/docs/extend/python.md index 1588f65..484547d 100644 --- a/docs/extend/python.md +++ b/docs/extend/python.md @@ -112,8 +112,8 @@ couch = Part.create(api, { Each part can have multiple parameters like resistance, voltage or capacitance. For the sofa length and weight make sense. Each parameter has a parameter template that combines the parameter name with a unit. So we first have to create the parameter templates and afterwards add the parameter values to the sofa. ```python -from inventree.base import Parameter -from inventree.base import ParameterTemplate +from inventree.part import Parameter +from inventree.part import ParameterTemplate LengthTemplate = ParameterTemplate.create(api, { 'name' : 'Length', 'units' : 'Meters' }) WeightTemplate = ParameterTemplate.create(api, { 'name' : 'Weight', 'units' : 'kg' }) @@ -162,7 +162,7 @@ Please recognize the different status flags. 10 means OK, 55 means damaged. We h #### Adding manufacturers and supplier -We can add manufacturers and suppliers to parts. If we add a manufacturer, a supplier is also mandatory. So we first need to create two companies, ACME (manufacturer) and X-Store (supplier). +We can add manufacturers and suppliers to parts. We first need to create two companies, ACME (manufacturer) and X-Store (supplier). ```python from inventree.company import Company @@ -198,11 +198,15 @@ SupplierPart.create(api,{ 'part':couch.pk, 'supplier':xstore.pk, 'SKU':'some_code', - 'manufacturer':acme.pk + 'link':'https://www.xst.bla/products/stock?...' +}) +SupplierPart.create(api,{ + 'part':couch.pk, + 'manufacturer':acme.pk, + 'MPN':'Part code of the manufacturer' }) -``` -Supplier and manufacturer are added with just one command. The SKU is the code under which the couch is listed in the store. +``` #### Add a datasheet or other documents We have the possibility to add documents to the part. We can use pdf for documents but also other files like 3D drawings or pictures. To do so we add the following commands: diff --git a/docs/faq.md b/docs/faq.md index ba68ccf..829448f 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -4,6 +4,22 @@ title: FAQ ## Frequently Asked Questions +### Errors during InvenTree update + +Sometimes, users may encounter unexpected error messages when updating their InvenTree installation to a newer version. + +The most common problem here is that the correct sequenct of steps is followed: + +1. Ensure that the InvenTree web server and background worker processes are *halted* +1. Update the InvenTree software (e.g. using git or docker, depending on installation method) +1. Run the `invoke update` command +1. Restart the web server and background worker processes + +For more information, refer to the installation guides: + +- [Docker Installation](./start/docker_prod.md#updating-inventree) +- [Bare Metal Installation](./start/update.md) + ### Feature *x* is not visible after update If a particular menu / item is not visible after updating InvenTree, it may be due to your internet browser caching old versions of CSS and JavaScript files. diff --git a/docs/features.md b/docs/features.md index 78d76e4..521dff9 100644 --- a/docs/features.md +++ b/docs/features.md @@ -22,7 +22,7 @@ Parts are the fundamental element of any inventory. InvenTree groups parts into InvenTree allows you to easily create, modify or delete suppliers and supplier items linked to any part in your inventory. -[Read more...](./companies/supplier.md) +[Read more...](./buy/supplier.md) ## Instant Stock Knowledge diff --git a/docs/part/create.md b/docs/part/create.md index dfdef97..178e829 100644 --- a/docs/part/create.md +++ b/docs/part/create.md @@ -30,7 +30,7 @@ Once the form is completed, the browser window is redirected to the new part det If the *Create Initial Stock* setting is enabled, then an extra section is available in the part creation form to create an initial quantity of stock for the newly created part: -{% with id="setting", url="part/create_initial_stock_option.png", descript="Create stock option" %} +{% with id="setting", url="part/create_initial_stock_option.png", description="Create stock option" %} {% include "img.html" %} {% endwith %} diff --git a/docs/part/part.md b/docs/part/part.md index 274ab93..dd48507 100644 --- a/docs/part/part.md +++ b/docs/part/part.md @@ -55,7 +55,7 @@ Trackable parts can be assigned batch numbers or serial numbers which uniquely i ### Purchaseable -If a part is designated as *Purchaseable* it can be purchased from external suppliers. Setting this flag allows parts to be added to [purchase orders](../companies/po.md). +If a part is designated as *Purchaseable* it can be purchased from external suppliers. Setting this flag allows parts to be added to [purchase orders](../buy/po.md). ### Salable diff --git a/docs/part/pricing.md b/docs/part/pricing.md index 4c5d7d1..d1c7a4e 100644 --- a/docs/part/pricing.md +++ b/docs/part/pricing.md @@ -54,9 +54,9 @@ If a part is an assembly this panel will show the cost (possibly as range) for a ### Sale cost / prices -Sale prices are always to customers (through [sale orders](../companies/so.md)) and support [price ranges](#price-ranges). +Sale prices are always to customers (through [sale orders](../sell/so.md)) and support [price ranges](#price-ranges). -The panel also shows historical sale price information collected from past [purchase orders](../companies/po.md). +The panel also shows historical sale price information collected from past [purchase orders](../buy/po.md). ## Currency conversion diff --git a/docs/part/trackable.md b/docs/part/trackable.md index 4544435..e9c015c 100644 --- a/docs/part/trackable.md +++ b/docs/part/trackable.md @@ -8,7 +8,7 @@ Denoting a part as *Trackble* changes the way that [stock items](../../stock/sto For many parts in an InvenTree database, simply tracking current stock levels (and locations) is sufficient. However, some parts require more extensive tracking than simple stock level knowledge. -Any stock item associated with a trackable part *must* have either a batch number or a serial number. This includes stock created manually or via an internal process (such as a [Purchase Order](../companies/po.md) or a [Build Order](../build/build.md)). +Any stock item associated with a trackable part *must* have either a batch number or a serial number. This includes stock created manually or via an internal process (such as a [Purchase Order](../buy/po.md) or a [Build Order](../build/build.md)). ## Assign Serial Numbers @@ -29,8 +29,8 @@ For faster input there are several ways to define the wanted serial numbers(SN): These rules can be mix-and-matched with whitespaces or commas separating them. For example: `1 3-5 9+2` or `1,3-5,9+2` result in `[1, 3, 4, 5, 9, 10, 11]` -`~+2`(with next SN beeing 14) results in `[14, 15, 16]` -`~+`(with next SN beeing 14 and 2 numbers needed) results in `[14, 15]` +`~+2`(with next SN being 14) results in `[14, 15, 16]` +`~+`(with next SN being 14 and 2 numbers needed) results in `[14, 15]` ## Build Orders diff --git a/docs/part/views.md b/docs/part/views.md index c743c3d..b0c7b3e 100644 --- a/docs/part/views.md +++ b/docs/part/views.md @@ -122,6 +122,36 @@ This tab is only displayed if the part is marked as *Purchaseable*. The *Sales Orders* tab shows a list of the sales orders for this part. It provides a view for important sales order information like customer, status, creation and shipment dates. +### Scheduling + +The *Scheduling* tab provides an overview of the *predicted* future availabile quantity of a particular part. + +The *Scheduling* tab displays a chart of estimated future part stock levels. It begins at the current date, with the current stock level. It then projects into the "future", taking information from: + +#### Incoming Stock + +- **Purchase Orders** - Incoming goods will increase stock levels +- **Build Orders** - Completed build outputs will increase stock levels + +#### Outgoing Stock + +- **Sales Orders** - Outgoing stock items will reduce stock levels +- **Build Orders** - Allocated stock items will reduce stock levels + +#### Caveats + +The scheduling information only works as an adequate predictor of future stock quantity if there is sufficient information available in the database. + +In particular, stock movements due to orders (Purchase Orders / Sales Orders / Build Orders) will only be counted in the scheduling *if a target date is set for the order*. If the order does not have a target date set, we cannot know *when* (in the future) the stock levels will be adjusted. Thus, orders without target date information do not contribute to the scheduling information. + +Additionally, any orders with a target date in the "past" are also ignored for the purpose of part scheduling. + +Finally, any unexpected or unscheduled stock operations which are not associated with future orders cannot be predicted or displayed in the scheduling tab. + +{% with id="scheduling", url="part/scheduling.png", description="Part Scheduling View" %} +{% include 'img.html' %} +{% endwith %} + ### Tests If a part is marked as *trackable*, the user can define tests which must be performed on any stock items which are instances of this part. [Read more about testing](./test.md). diff --git a/docs/releases/0.1.8.md b/docs/releases/0.1.8.md index 50d6874..6e8cd20 100644 --- a/docs/releases/0.1.8.md +++ b/docs/releases/0.1.8.md @@ -29,7 +29,7 @@ title: Release 0.1.8 ### Assign by Serial Number -[#1426](https://github.com/inventree/InvenTree/pull/1426) introduces a new feature which allows stock items to be allocated to a sales order using serial number references. This provides a much more streamlined user experience. Refer to the [sales order documentation](../companies/so.md) for further information. +[#1426](https://github.com/inventree/InvenTree/pull/1426) introduces a new feature which allows stock items to be allocated to a sales order using serial number references. This provides a much more streamlined user experience. Refer to the [sales order documentation](../sell/so.md) for further information. ## Major Bug Fixes diff --git a/docs/releases/0.2.1.md b/docs/releases/0.2.1.md index 2e23fba..339ee11 100644 --- a/docs/releases/0.2.1.md +++ b/docs/releases/0.2.1.md @@ -26,7 +26,7 @@ sourcing information for a part. Soon, InvenTree will allow the use of manufacturer data directly in purchase orders. Details on how to create and manage manufacturer parts were added -[here](../companies/manufacturer.md#add-manufacturer-part). +[here](../buy/manufacturer.md#add-manufacturer-part). ### URL-style QR Code for StockItem diff --git a/docs/releases/0.6.1.md b/docs/releases/0.6.1.md index 39bbb32..5836cd2 100644 --- a/docs/releases/0.6.1.md +++ b/docs/releases/0.6.1.md @@ -10,6 +10,11 @@ For a comprehensive list of changes associated with this release, refer to the [ ## Bug Fixes -!!! info "TODO" - -This section is a work in progress. +| Pull Request | Description | +| --- | --- | +| [#2666](https://github.com/inventree/InvenTree/pull/2666) | Fixes bug when creating build output via the API | +| [#2673](https://github.com/inventree/InvenTree/pull/2673) | Bug fixes for allocating stock items against a build order | +| [#2676](https://github.com/inventree/InvenTree/pull/2676) | Fixes HTML template bug for StockLocation display | +| [#2682](https://github.com/inventree/InvenTree/pull/2682) | Fixes plugin bug when running alongisde old (< 2.2.0) version of Git | +| [#2696](https://github.com/inventree/InvenTree/pull/2696) | Fixes some template / javascript rendering issues for the Part detail page | +| [#2697](https://github.com/inventree/InvenTree/pull/2697) | Fixes a coding bug determining if parts were fully allocated against a build order | diff --git a/docs/releases/0.6.2.md b/docs/releases/0.6.2.md new file mode 100644 index 0000000..e877fa0 --- /dev/null +++ b/docs/releases/0.6.2.md @@ -0,0 +1,18 @@ +--- +title: Release 0.6.2 +--- + +## Release 0.6.2 + +Release 0.6.2 is a bug-fix release on the 0.6.x stable branch. + +For a comprehensive list of changes associated with this release, refer to the [InvenTree GitHub page](https://github.com/inventree/InvenTree/milestone/15). + +## Bug Fixes + +| Pull Request | Description | +| --- | --- | +| [#2717](https://github.com/inventree/InvenTree/pull/2717) | Fixes bug which occured when empty serial number strings were supplied | +| [#2720](https://github.com/inventree/InvenTree/pull/2720) | Fixes bug which prevented barcode scanning from working | +| [#2721](https://github.com/inventree/InvenTree/pull/2721) | Fixes bug which occured when an arbitrarily large serial number was supplied | +| [#2736](https://github.com/inventree/InvenTree/pull/2736) | Fixes incorrect behaviour when a PartCategory or StockLocation is deleted | diff --git a/docs/releases/0.6.3.md b/docs/releases/0.6.3.md new file mode 100644 index 0000000..fc9b10b --- /dev/null +++ b/docs/releases/0.6.3.md @@ -0,0 +1,15 @@ +--- +title: Release 0.6.3 +--- + +## Release 0.6.3 + +Release 0.6.3 is a bug-fix release on the 0.6.x stable branch. + +For a comprehensive list of changes associated with this release, refer to the [InvenTree GitHub page](https://github.com/inventree/InvenTree/milestone/16). + +## Bug Fixes + +| Pull Request | Description | +| --- | --- | +| [#2751](https://github.com/inventree/InvenTree/pull/2751) | Fixes bug which incorrectly displays amount of stock allocated to sales orders | diff --git a/docs/releases/0.6.4.md b/docs/releases/0.6.4.md new file mode 100644 index 0000000..eed37f4 --- /dev/null +++ b/docs/releases/0.6.4.md @@ -0,0 +1,17 @@ +--- +title: Release 0.6.4 +--- + +## Release 0.6.4 + +Release 0.6.4 is a bug-fix release on the 0.6.x stable branch. + +For a comprehensive list of changes associated with this release, refer to the [InvenTree GitHub page](https://github.com/inventree/InvenTree/milestone/18). + +## Bug Fixes + +| Pull Request | Description | +| --- | --- | +| [#2812](https://github.com/inventree/InvenTree/pull/2812) | Fixes HTML templating error for Part and PurchaseOrder importers | +| [#2842](https://github.com/inventree/InvenTree/pull/2842) | Fixes potential XSS vulnerability in jquery-ui package | +| [#2859](https://github.com/inventree/InvenTree/pull/2859) | Fixes bug which improperly checks for unique IPN values | \ No newline at end of file diff --git a/docs/releases/0.7.0.md b/docs/releases/0.7.0.md index 4e317f4..80d4f79 100644 --- a/docs/releases/0.7.0.md +++ b/docs/releases/0.7.0.md @@ -6,8 +6,93 @@ title: Release 0.7.0 0.7.0 is a major feature release of the InvenTree software project. For a comprehsive list of changes associated with this release, please refer to the [InvenTree GitHub page](https://github.com/inventree/InvenTree/milestone/10). +### Plugins + +In addition to providing a slew of new features and stability improvements (as listed below), this version focuses heavily on improvements to the [plugin system](../extend/plugins.md). The plugin ecosystem has received a major overhaul, and now provides a number of new plugin "mixins" for supporting custom functionality. The plugin system will continue to receive attention over the next major release cycle. + + +!!! warning "Plugin Changes" + Version `0.7.0` introduces some major changes (improvements) to the plugin interface. If you are updating from a previous version, any custom plugins you have installed may also need to be updated. + +### Unit Testing + +This release also provides a marked improvement in unit testing and code coverage. The project is now above 85% code coverage! This is a great milestone, but we can do better! We will continue to improve our unit testing to ensure that InvenTree remains a high quality, stable software product. + ## New Features -!!! info "TODO" +### Order Target Dates -This section is a work in progress. +[#2684](https://github.com/inventree/InvenTree/pull/2684) adds a `target_date` field to both the PurchaseOrderLineItem and SalesOrderLineItem models, separate to the `target_date` field on the parent _Order_ models. This allows expected shipment dates to be specified for individual line items. + +### It's a Date! + +[#2685](https://github.com/inventree/InvenTree/pull/2685) adds the ability for users to customize how dates are formatted and displayed in the web interface. + +### Serialize Incoming Stock + +[#2686](https://github.com/inventree/InvenTree/pull/2686) provides the ability to add batch codes and serial numbers to incoming stock items received against purchase orders. + +### Persistent Forms + +[#2687](https://github.com/inventree/InvenTree/pull/2687) adds the ability for modal forms to be "persistent" - i.e. they are not immediately dismissed after successful submission. This allows (for example) the "Create Part" form to be used multiple times in succession, allowing quick creation of parts by the user. + +### Stock Scheduling + +[#2695](https://github.com/inventree/InvenTree/pull/2695) adds a new "Scheduling" tab to the "Part" display. This displays projected / predicted future stock levels, based on pending orders. + +### Automatic Stock Allocation + +[#2713](https://github.com/inventree/InvenTree/pull/2713) adds a feature to "automatically" allocate stock items to a build order. + +### Extra, Extra + +[#2714](https://github.com/inventree/InvenTree/pull/2714) adds "extra line items" to purchase orders and sales orders. This allows tracking of line items which are not associated with a part in the database (e.g. fees, charges) + +### Notifications + +[#2372](https://github.com/inventree/InvenTree/pull/2372) provides an overhaul of notifications, allowing users to view their notifications directly in the InvenTree interface. + +### Why are you hiding my name? +[#2861](https://github.com/inventree/InvenTree/pull/2861) adds several changes to enable admins to remove more of InvenTrees branding. Change logo, hide the about-modal for all but superusers and add custom messages to login and main navbar. Check out [the docs](../start/config.md#customisation-options). + +### Label Printing Plugin + +[#2768](https://github.com/inventree/InvenTree/pull/2768) adds a new LabelPrinting plugin class, which allows printing labels directly to external printers (e.g. via local network). + +### New Search Menu + +[#2783](https://github.com/inventree/InvenTree/pull/2783) introduces a new quick search menu which provides more comprehensive search results for quicker data access. + +### BOM Stock Data + +The Bill of Materials tables now display a more comprehensive view of available stock, including stock for variant parts, and stock for substitute parts. This allows users a better picture of what stock is actually available for use. + +### Docker Improvements + +Multiple improvements have been made to the docker installation process, most notably updated docker-compose files for development and production setups. Docker setup time and complexity should now be significantly reduced. + +### Build Order Improvements + +[#2893](https://github.com/inventree/InvenTree/pull/2893) provides a number of improvements to the build order process. Most notable is a complete overhaul of the "build output" window, providing a more efficient user experience. + +### Multi Level BOM Fix + +[#2901](https://github.com/inventree/InvenTree/pull/2901) overhauls the way that multi level BOMs are displayed. Instead of loading *all* BOM data by default, a flat top-level BOM is first loaded, and then the user has the option to load BOMs from subassemblies into the same table. + +### QR code scanner + +[#2779](https://github.com/inventree/InvenTree/pull/2779) provides a QR code scanner which can be used to quickly scan Inventree generated QR codes using webcams or mobile devices. This feature requires secure (HTTPS) connection to the server. + +### Order, Order + +[#2770](https://github.com/inventree/InvenTree/pull/2770) implements a major overhaul of the "order parts" wizard, with the form now making use of the API rather than being rendered on the server. + +### Panel Plugins + +[#2937](https://github.com/inventree/InvenTree/pull/2937) adds a new type of plugin mixin, which allows rendering of custom "panels" on certain pages. This is a powerful new plugin feature which allows custom UI elements to be generated with ease. Read more about this new mixin [here](../extend/plugins/panel.md). + +## Bug Fixes + +| Pull Request | Description | +| --- | --- | +| [#2869](https://github.com/inventree/InvenTree/pull/2869) | Fixes Part API bug | diff --git a/docs/releases/0.7.1.md b/docs/releases/0.7.1.md new file mode 100644 index 0000000..7a3eb44 --- /dev/null +++ b/docs/releases/0.7.1.md @@ -0,0 +1,17 @@ +--- +title: Release 0.7.0 +--- + +## Release: 0.7.1 + +Release 0.7.1 is a bug-fix release on the 0.7.x stable branch. + +For a comprehensive list of changes associated with this release, refer to the [InvenTree GitHub page](https://github.com/inventree/InvenTree/milestone/19). + +## Bug Fixes + +| Pull Request | Description | +| --- | --- | +| [#3075](https://github.com/inventree/InvenTree/pull/3075) | Fixes an unhandled exception when converting currency without any available exchange rate data | +| [#3083](https://github.com/inventree/InvenTree/pull/3083) | Fixes search bug related to user permissions | +| [#3115](https://github.com/inventree/InvenTree/pull/3115) | Fix for purchase order table on supplier part page | diff --git a/docs/releases/0.8.0.md b/docs/releases/0.8.0.md new file mode 100644 index 0000000..c904dc5 --- /dev/null +++ b/docs/releases/0.8.0.md @@ -0,0 +1,26 @@ +--- +title: Release 0.8.0 +--- + +## Release: 0.8.0 + +0.8.0 is a major feature release of the InvenTree software project. For a comprehsive list of changes associated with this release, please refer to the [InvenTree GitHub page](https://github.com/inventree/InvenTree/milestone/14). + +## New Features + +### Dockerfile Improvements + +[#3042](https://github.com/inventree/InvenTree/pull/3042) provides a major overhaul of the InvenTree docker image and docker-compose files, providing significant improvements in terms of image size and build time. + +### Shipment Features + +[#3058](https://github.com/inventree/InvenTree/pull/3058) implements new data fields for the [Sales Order Shipment](../sell/shipment.md). + +### Calendar Displays + +[#3070](https://github.com/inventree/InvenTree/pull/3070) improves existing calendar displays for "order" tables and paves the way for future calendar improvements. + +## Bug Fixes + +| Pull Request | Description | +| --- | --- | diff --git a/docs/releases/release_notes.md b/docs/releases/release_notes.md index 5fa5053..9915637 100644 --- a/docs/releases/release_notes.md +++ b/docs/releases/release_notes.md @@ -15,18 +15,29 @@ The head of the *stable* code branch represents the most recent stable tagged re ### Development Branch -The head of the *master* code branch represents the "latest and greatest" working codebase. All features and bug fixes are merged into the master branch, in addition to relevent stable release branches. +The head of the *master* code branch represents the "latest and greatest" working codebase. All features and bug fixes are merged into the master branch, in addition to relevant stable release branches. !!! info " Latest Docker" To pull down the latest *development* version of InvenTree in docker, use `inventree/inventree:latest` ## Stable Releases -Specific tagged released are shown below. Click on the release notes for each version to learn more. +Specific tagged releases are shown below. Click on the release notes for each version to learn more. + +### 0.7.x +| Release | Date | GitHub | Docker | +| --- | --- | --- | --- | +| [0.7.1](./0.7.1.md) | 2022-06-02 | [0.7.1](https://github.com/inventree/InvenTree/releases/tag/0.7.1) | [inventree:0.7.1](https://hub.docker.com/layers/inventree/inventree/inventree/0.7.1/images/sha256-5da112efd1aa43d2e22df7053e6344e884d094aaddcf6401f0ccbaac245e61da?context=explore) | +| [0.7.0](./0.7.0.md) | 2022-05-24 | [0.7.0](https://github.com/inventree/InvenTree/releases/tag/0.7.0) | [inventree:0.7.0](https://hub.docker.com/layers/inventree/inventree/inventree/0.7.0/images/sha256-b15d2970e1577cc8e2429487636f07576912cec8d3c7ee0227c3e51711f0042a?context=explore) | + ### 0.6.x | Release | Date | GitHub | Docker | | --- | --- | --- | --- | +| [0.6.4](./0.6.4.md) | 2022-05-10 | [0.6.4](https://github.com/inventree/InvenTree/releases/tag/0.6.4) | [inventree:0.6.4](https://hub.docker.com/layers/inventree/inventree/inventree/0.6.4/images/sha256-9b89052490e6b43edc541f2a0856397db85742749fa8f2a262a0654b0532f7a9?context=explore) | +| [0.6.3](./0.6.3.md) | 2022-03-30 | [0.6.3](https://github.com/inventree/InvenTree/releases/tag/0.6.3) | [inventree:0.6.3](https://hub.docker.com/layers/inventree/inventree/inventree/0.6.3/images/sha256-dc583301371686a30c919a25dd68e5101ea9ecb8cb63dde617fa8b2c44c27ff6?context=explore) | +| [0.6.2](./0.6.2.md) | 2022-03-10 | [0.6.2](https://github.com/inventree/InvenTree/releases/tag/0.6.2) | [inventree:0.6.2](https://hub.docker.com/layers/inventree/inventree/0.6.2/images/sha256-09e8a4a95285906b4d1d5dbd2274f56595f0b402c296d59eca2c8534c0242257?context=explore) | +| [0.6.1](./0.6.1.md) | 2022-03-04 | [0.6.1](https://github.com/inventree/InvenTree/releases/tag/0.6.1) | [inventree:0.6.1](https://hub.docker.com/layers/inventree/inventree/0.6.1/images/sha256-7586a9feaa50e2928742ea4b0a6441505984b196105a7f84b70b845d42e4af75?context=explore) | | [0.6.0](./0.6.0.md) | 2022-02-21 | [0.6.0](https://github.com/inventree/InvenTree/releases/tag/0.6.0) | [inventree:0.6.0](https://hub.docker.com/layers/inventree/inventree/0.6.0/images/sha256-7f4d936d8647ee107a04752f13265687c580c89d5afdd4565e7073f2c32b357a?context=explore) | ### 0.5.x diff --git a/docs/report/bom.md b/docs/report/bom.md new file mode 100644 index 0000000..f656d25 --- /dev/null +++ b/docs/report/bom.md @@ -0,0 +1,113 @@ +--- +title: BOM Generation +--- + +## BOM Generation +The bill of materials is an essential part of the documentation that needs to be sent to the factory. A simple csv export is OK to be important into SMT machines. But for human readable documentation it might not be sufficient. Additional information is needed. The Inventree report system allows to generate BOM well formatted BOM reports. + +### A simple example +The following picture shows a simple example for a PCB with just three components from two different parts. + +{% with id="report-options", url="report/bom_example.png", description="BOM example" %} {% include 'img.html' %} {% endwith %} + +This example has been created using the following html template: + +```html +{% raw %} +{% extends "report/inventree_report_base.html" %} + +{% load i18n %} +{% load report %} +{% load inventree_extras %} + +{% block page_margin %} +margin-left: 2cm; +margin-right: 1cm; +margin-top: 4cm; +{% endblock %} + +{% block bottom_left %} +content: "v{{report_revision}} - {{ date.isoformat }}"; +{% endblock %} + +{% block bottom_center %} +content: "InvenTree v{% inventree_version %}"; +{% endblock %} + +{% block style %} +.header-left { + text-align: left; + float: left; +} +table { + border: 1px solid #eee; + border-radius: 3px; + border-collapse: collapse; + width: 100%; + font-size: 80%; +} +table td { + border: 1px solid #eee; +} +{% endblock %} + +{% block header_content %} +
+

{% trans "Bill of Materials" %}

+
+{% endblock %} + +{% block page_content %} + + + + + + +
Board{{ part.IPN }}
Description{{ part.description }}
User{{ user }}
Date{{ date }}
Number of different components (codes){{ bom_items.count }}
+
+ + + + + + + + + + + + + {% for line in bom_items.all %} + + + + + + + + + {% endfor %} + +
{% trans "IPN" %}{% trans "MPN" %}{% trans "Manufacturer" %}{% trans "Quantity" %}{% trans "Reference" %}{% trans "Substitute" %}
{{ line.sub_part.IPN }}{{ line.sub_part.name }} + {% for manf in line.sub_part.manufacturer_parts.all %} + {{ manf.manufacturer.name }} + {% endfor %} + {% decimal line.quantity %}{{ line.reference }} + {% for sub in line.substitutes.all %} + {{ sub.part.IPN }}
+ {% endfor %} +
+ +{% endblock %} +{% endraw %} +``` + +### Context variables +| Variable | Description | +| --- | --- | +| bom_items | Query set that contains all BOM items | +| bom_items...sub_part | One component of the BOM | +| bom_items...quantity | Number of parts | +| bom_items...reference | Reference designators of the part | +| bom_items...substitutes | Query set that contains substitutes of the part if any exist in the BOM | diff --git a/docs/report/build.md b/docs/report/build.md index a29b149..b642b53 100644 --- a/docs/report/build.md +++ b/docs/report/build.md @@ -9,7 +9,7 @@ Custom build order reports may be generated against any given Build Order. For e ### Build Filters !!! missing "TODO" - This section rquires further work + This section requires further work ### Context Variables @@ -19,8 +19,89 @@ In addition to the default report context variables, the following context varia | --- | --- | | build | The [Build](./context_variables.md#build) object the report is being generated against | | part | The [Part](./context_variables.md#part) object that the build references | -| reference | The build order reference string | +| reference | The build order reference string. This is just the string that follows BO... | +| title | The full name of the build including the BO | | quantity | Build order quantity | +| build.title | The description of the build | +| build.status | The status of the build. 20 means 'Production' | +| build.bom_items | A query set with all bom items for the build | +bom_items that can be looped. Each bom_item line has further context variables. +| Variable | Description | +| --- | --- | +| line.reference | The reference designator of the component | +| line.sub_part | The part at this position | +| line.quantity | The number of components | +| line.sub_part.build_order_allocations | ... | +A very simple example wihtout any html formatting: + +{% raw %} +```html +reference: {{reference }} +
+quantity: {{ quantity }} +
+title: {{ title }} +
+part: {{ part }} +
+build: {{ build }} +
+
+build.reference: {{ build.reference }} +
+build.title: {{ build.title }} +
+build.status: {{ build.status }} +
+------- +
+{% for line in build.bom_items %} +reference:: {{ line.reference }} +
+quantity:: {{ line.quantity }} +
+sub_part: {{ line.sub_part }} +
+sub_part.IPN: {{ line.sub_part.IPN }} +
+sub_part.name: {{ line.sub_part.name }} +
+sub_part.build_order_allocations: {{ line.sub_part.build_order_allocations }} +
+........ +
+{% endfor %} +``` + +This will result in: + +```text +reference: 0001 +quantity: 10 +title: BO0001 +part: POP-000001-001 | Converter - A to B +build: BO0001 + +build.reference: 0001 +build.title: Description of the build +build.status: 20 +------- +reference:: U002 +quantity:: 1.00000 +sub_part: ANA-000001-001 | op701 - operation amplifier +sub_part.IPN: ANA-000001-001 +sub_part.name: op701 +sub_part.build_order_allocations: ]> +........ +reference:: U001 +quantity:: 2.00000 +sub_part: ANA-000002-001 | L7805 - LDO +sub_part.IPN: ANA-000002-001 +sub_part.name: L7805 +sub_part.build_order_allocations: ]> +........ +``` +{% endraw %} diff --git a/docs/report/report.md b/docs/report/report.md index e2a996b..4f98d66 100644 --- a/docs/report/report.md +++ b/docs/report/report.md @@ -193,7 +193,11 @@ InvenTree supports the following reporting functionality: [Purchase Order report](./order.md): Order line items ### Sales Order -Sales Order: TODO + +!!! missing "TODO" + This section requires further work ### Stocktake -Stocktake Report: TODO + +!!! missing "TODO" + This section requires further work diff --git a/docs/report/test.md b/docs/report/test.md index 19da203..89b9018 100644 --- a/docs/report/test.md +++ b/docs/report/test.md @@ -19,7 +19,7 @@ A TestReport template may define a set of filters against which parts are sorted This allows each TestReport to easily be assigned to a particular Part, or even multiple parts. -In the example below, a test report template is uploaded and assigned to the part with the name *"My Widget"*. Any combination of fields relevent to the Part model can be used here. +In the example below, a test report template is uploaded and assigned to the part with the name *"My Widget"*. Any combination of fields relevant to the Part model can be used here. {% with id="test_report_add", url="admin/test_report_add.png", description="Upload test report template" %} {% include 'img.html' %} diff --git a/docs/companies/customer.md b/docs/sell/customer.md similarity index 100% rename from docs/companies/customer.md rename to docs/sell/customer.md diff --git a/docs/sell/shipment.md b/docs/sell/shipment.md new file mode 100644 index 0000000..855abc6 --- /dev/null +++ b/docs/sell/shipment.md @@ -0,0 +1,71 @@ +--- +title: Shipments +--- + +## Shipments + +Shipments are used to track sales items when they are shipped to customers. Multiple shipments can be created against a [Sales Order](./so.md), allowing line items to be sent to customers in multiple deliveries. + +On the main Sales Order detail page, the order shipments are split into two categories, *Pending Shipments* and *Completed Shipments*: + +### Pending Shipments + +The *Pending Shipments* panel displays the shipments which have not yet been sent to the customer. + +- Each shipment displays the items which have been allocated to it +- Pending sales order items can be allocated to these shipments +- New shipments can be created if the order is still open + +{% with id="pending-shipments", url="sell/pending_shipments.png", description="Pending shipments" %} +{% include "img.html" %} +{% endwith %} + +#### Creating a new Shipment + +To create a new shipment for a sales order, press the *New Shipment* button above the pending shipments table. + +#### Completing a Shipment + +To complete a shipment, press the *Complete Shipment* button associated with the particular shipment: + +{% with id="complete-shipment", url="sell/complete_shipment.png", description="Complete shipment" %} +{% include "img.html" %} +{% endwith %} + +Alternatively, pending shipments can be completed by selecting the *Complete Shipments* action from the sales order actions menu: + +{% with id="complete-shipment-action", url="sell/complete_shipment_action.png", description="Complete shipment" %} +{% include "img.html" %} +{% endwith %} + +### Completed Shipments + +{% with id="completed-shipments", url="sell/completed_shipments.png", description="Completed shipments" %} +{% include "img.html" %} +{% endwith %} + +### Shipment Data + +Each shipment provides the following data fields: + +#### Reference + +A unique number for the shipment, used to identify each shipment within a sales order. By default, this value starts at `1` for the first shipment (for each order) and automatically increments for each new shipment. + +#### Tracking Number + +An optional field used to store tracking number information for the shipment. + +#### Invoice Number + +An optional field used to store an invoice reference for the shipment. + +#### Link + +An optional URL field which can be used to provide a link to an external URL. + +All these fields can be edited by the user: + +{% with id="edit-shipment", url="sell/edit_shipment.png", description="Edit shipment" %} +{% include "img.html" %} +{% endwith %} diff --git a/docs/companies/so.md b/docs/sell/so.md similarity index 97% rename from docs/companies/so.md rename to docs/sell/so.md index 58dc050..221f6cb 100644 --- a/docs/companies/so.md +++ b/docs/sell/so.md @@ -32,7 +32,7 @@ Fill out the rest of the form then click on button +- enable the ["Import Parts" tab in the part category view](../part/part.md#part-import). + +| Setting | Type | Description | Default | +| --- | --- | --- | --- | +| Show Import in Views | Boolean | Display the import wizard in some part views | True | + +#### Part Parameter Templates + +Refer to the section describing [how to create part parameter templates](../part/parameter.md#create-template). ### Categories -Configuration of Part Category options +In this section of the settings, staff users can set a list of parameters associated to a part category. + +To add a parameter to a part category: + +1. select the category in the dropdown list +2. click the New Parameter button on the top right +3. fill out the "Create Category Parameter Template" form +4. click the Submit button. + +After a list of parameters is added to a part category and upon creation of a new part in this category, this list of parameters will be added by default to the new part. ### Stock -Configuration of Stock Item options +Configuration of stock item options | Setting | Type | Description | Default | | --- | --- | --- | --- | diff --git a/docs/settings/permissions.md b/docs/settings/permissions.md index e191b93..714577e 100644 --- a/docs/settings/permissions.md +++ b/docs/settings/permissions.md @@ -11,7 +11,7 @@ InvenTree provides access control to various features and data, by assigning eac ### User -A *user* is a single unique account with login credentials. By default, a user is not afforded *any* permissions, and the user must be assigned to the relevent group for the permissions to be assigned. +A *user* is a single unique account with login credentials. By default, a user is not afforded *any* permissions, and the user must be assigned to the relevant group for the permissions to be assigned. ### Group diff --git a/docs/start/config.md b/docs/start/config.md index b0a6557..06dc741 100644 --- a/docs/start/config.md +++ b/docs/start/config.md @@ -48,6 +48,16 @@ The following basic options are available: | INVENTREE_LOG_LEVEL | log_level | Set level of logging to terminal | WARNING | | INVENTREE_PLUGINS_ENABLED | plugins_enabled | Enable plugin support | False | +## Administrator Account + +An administrator account can be specified using the following environment variables: + +| Environment Variable | Settings File | Description | Default | +| --- | --- | --- | --- | +| INVENTREE_ADMIN_USER | admin_user | Admin account username | *Not set* | +| INVENTREE_ADMIN_PASSWORD | admin_password | Admin account password | *Not set* | +| INVENTREE_ADMIN_EMAIL | admin_email |Admin account email address | *Not set* | + ## Secret Key InvenTree requires a secret key for providing cryptographic signing - this should be a secret (and unpredictable) value. @@ -156,6 +166,18 @@ The login-experience can be altered with the following settings: Custom authentication backends can be used by specifying them here. These can for example be used to add [LDAP / AD login](https://django-auth-ldap.readthedocs.io/en/latest/) to InvenTree +### Customisation Options + +The logo and custom messages can be changed/set: + +| Environment Variable | Settings File | Description | Default | +| --- | --- | --- | --- | +| INVENTREE_CUSTOM_LOGO | customize.logo | Path to logo in the media storage | | +| INVENTREE_CUSTOMIZE | customize.login_message | Custom message for login page | | +| INVENTREE_CUSTOMIZE | customize.navbar_message | Custom message for navbar | | + +If you want to remove the InvenTree branding as far as possible from your end-user also check the [global server settings](../settings/global.md#server-settings). + ## Other Options ### Middleware diff --git a/docs/start/docker.md b/docs/start/docker.md index afa7441..28fa948 100644 --- a/docs/start/docker.md +++ b/docs/start/docker.md @@ -26,39 +26,15 @@ InvenTree provides sample docker-compose files to get you up and running. - A *development* compose file provides a simple way to spin up a development environment !!! warning "Docker Compose Version" - Tthe following guide is designed to work with docker-compose v1.x. There are currently known issues with [docker-compose v2 support](https://github.com/docker/compose/releases/tag/v2.0.0). If you are having issues with the docker installation guide, check the version of docker-compose you are running with the command `docker-compose --version`. + The following guide is designed to work with docker-compose v1.x. There are currently known issues with [docker-compose v2 support](https://github.com/docker/compose/releases/tag/v2.0.0). If you are having issues with the docker installation guide, check the version of docker-compose you are running with the command `docker-compose --version`. ### Environment Variables -InvenTree run-time configuration options described in the [configuration documentation](./config.md) can be passed to the InvenTree container as environment variables. +InvenTree run-time configuration options described in the [configuration documentation](./config.md) can be passed to the InvenTree container as environment variables. Using environment variables simplifies setup and improves portability. -The following environment variables for InvenTree server configuration are specified as part of the docker image, and can be overridden if required: +### Persistent Data -| Variable | Description | Default Value | -| --- | --- | --- | -| INVENTREE_LOG_LEVEL | InvenTree logging verbosity level |INFO | -| INVENTREE_CONFIG_FILE | Location (within the docker image) of the InvenTree configuration file | /home/inventree/data/config.yaml | -| INVENTREE_SECRET_KEY_FILE | Location (within the docker image) of the InvenTree sercret key file | /home/inventree/data/secret_key.txt | -| INVENTREE_WEB_PORT | Internal container port on which the InvenTree web server is hosted | 8000 | - -The following environment variables are explicitly **not configured** and *must* be passed to the container instance: - -| Variable | Description | -| --- | --- | -| INVENTREE_DB_ENGINE | Database engine (e.g. 'postgresql') | -| INVENTREE_DB_NAME | Database name (e.g. 'inventree') | -| INVENTREE_DB_HOST | Database server host (e.g. 'inventree-server' if using default docker-compose script) | -| INVENTREE_DB_PORT | Database server port (e.g. '5432') | -| INVENTREE_DB_USER | Database user name (e.g. 'pguser') | -| INVENTREE_DB_PASSWORD | Database user password (e.g. 'pgpassword') | - -### Data Directory - -Persistent data (e.g. uploaded media files) should be stored outside the container instance. - -InvenTree data are stored inside the container at `/home/inventree/data`. - -This directory should be mounted as a volume which points to a directory on your local machine. +Persistent data (e.g. uploaded media files) is stored outside the container instance. This directory should be mounted as a volume which the InvenTree docker container can access. ### Configuration File @@ -79,15 +55,14 @@ By default, the InvenTree container expects the `INVENTREE_SECRET_KEY_FILE` to e !!! warning "Same Key" Each InvenTree container instance must use the same secret key value, otherwise unexpected behavior will occur. - ## Docker Setup Guides With these basics in mind, refer to the following installation guides: -### Development Server - -Refer to the [docker development server setup guide](./docker_dev.md) for instructions on configuring a development server using docker. - ### Production Server Refer to the [docker production server setup guide](./docker_prod.md) for instructions on configuring a production server using docker. + +### Development Server + +Refer to the [docker development server setup guide](./docker_dev.md) for instructions on configuring a development server using docker. diff --git a/docs/start/docker_dev.md b/docs/start/docker_dev.md index cfe97f6..08c1759 100644 --- a/docs/start/docker_dev.md +++ b/docs/start/docker_dev.md @@ -6,132 +6,80 @@ title: Docker Development Server You can use docker to launch and manage a development server, in a similar fashion to managing a production server. +The InvenTree dockerfile (`./Dockerfile`) uses a [multi-stage build](https://docs.docker.com/develop/develop-images/multistage-build/) process to allow both production and development setups from the same image. + There are some key differences compared to the [docker production setup](./docker_prod.md): - The docker image is built locally, rather than being downloaded from DockerHub -- The docker image points to the source code on your local machine, instead of cloning from GitHub +- The docker image points to the source code on your local machine (mounted as a 'volume' in the docker container) - The django webserver is used, instead of running behind Gunicorn - The server will automatically reload when code changes are detected !!! info "Static and Media Files" The development server runs in DEBUG mode, and serves static and media files natively. -The [InvenTree docker image](https://github.com/inventree/InvenTree/blob/master/docker/Dockerfile) uses a [multi-stage build](https://docs.docker.com/develop/develop-images/multistage-build/) process to allow both production and development setups from the same image. The key difference is that the production image is pre-built using InvenTree source code from GitHub, while the development image uses the source code from your local machine (allowing live code updates). +!!! info "Hacker Mode" + The following setup guide starts a development server which will reload "on the fly" as changes are made to the source code. This is designed for programmers and developers who wish to add and test new InvenTree features. -### Docker Compose +## Development Setup Guide -A docker compose script for running a development server is provided in the source repository at [./docker/docker-compose.dev.yml](https://github.com/inventree/InvenTree/blob/master/docker/docker-compose.dev.yml). +To get started with an InvenTree development setup, follow the simple steps outlined below. Before continuing, ensure that you have completed the following steps: -This script specifies the following containers: +- Downloaded the InvenTree source code to your local machine +- Installed docker on your local machine (install *Docker Desktop* on Windows) +- Have a terminal open to the root directory of the InvenTree source code -| Container | Description | -| --- | --- | -| inventree-dev-db | Database image (PostgreSQL) | -| inventree-dev-server | Web server using the django development server | -| inventree-dev-worker | Background task manager | +### Edit Environment Variables (Optional) -!!! success "Works out of the box" - You should not need to make any changes to the `docker-compose.dev.yml` file to run the development docker container +If desired, the user may edit the environment variables, located in the `.env` file. -#### PostgreSQL Database +!!! success "This step is optional" + This step can be skipped, as the default variables will work just fine! -A PostgreSQL database container requires a username:password combination (which can be changed). This uses the official [PostgreSQL image](https://hub.docker.com/_/postgres). +!!! info "Database Credentials" + You may also wish to change the database username (`INVENTREE_DB_USER`) and password (`INVENTREE_DB_PASSWORD`) from their default values -*__Note__: An empty database must be manually created as part of the setup (below)*. - -#### Web Server - -Runs an InvenTree web server instance, powered by Django's built-in webserver. - -#### Background Worker - -Runs the InvenTree background worker process. - -### Environment Variables - -Environment variables for the docker containers can be found in the file `dev-config.env` in the `docker` directory. - -!!! success "Works out of the box" - You should not normally need to change these variables from their default values. - -## Setup - -### Download Source Code - -First download the source code from GitHub: - -``` -git clone git@github.com:inventree/InvenTree.git inventree -``` - -### Build Docker Containers - -Build the docker containers with the following commands: - -``` -cd inventree/docker -docker-compose -f docker-compose.dev.yml build -``` - -### Create Database - -If this is the first time you are interacting with the docker containers, the InvenTree database has not yet been created. - -!!! success "First Run Only" - This command only needs to be executed on the first run, if the development database has not already been initialized - -Run the following command to open a shell session for the database - -``` -docker-compose -f docker-compose.dev.yml run inventree-dev-server pgcli -h inventree-dev-db -p 5432 -u pguser -``` - -!!! info "User" - If you have changed the `POSTGRES_USER` variable in the compose file, replace `pguser` with the different username. - -You will be prompted to enter the database user password (default="pgpassword", unless altered in the compose file). - -Once logged in, run the following command in the database shell: - -``` -create database inventree; -``` - -Then exit the shell with Ctrl+d - -### Database Setup +### Perform Initial Setup The database has now been created, but it is empty! Perform the initial database setup by running the following command: -``` -docker-compose -f docker-compose.dev.yml run inventree-dev-server invoke update +```bash +docker-compose run inventree-dev-server invoke update ``` -This command performs the following steps: +If this is the first time you are configuring the development server, this command will build a development version of the inventree docker image. + +This command also performs the following steps: - Ensure required python packages are installed - Perform the required schema updates to create the required database tables - Update translation files +- Collect all required static files into a directory where they can be served by nginx + +!!! info "Grab a coffee" + This initial build process may take a few minutes! ### Create Admin Account -!!! info "First Run Only" - This command only needs to be executed on the first run, if you have not already created a superuser account for the database +If you are creating the initial database, you need to create an admin (superuser) account for the database. Run the command below, and follow the prompts: ``` -docker-compose -f docker-compose.dev.yml run inventree-dev-server invoke superuser +docker-compose run inventree-dev-server invoke superuser ``` -This will prompt you to create a superuser account for the InvenTree instance. +### Start Docker Containers -### Run Containers - -Launch the server and worker containers with the following command: +Now that the database has been created, migrations applied, and you have created an admin account, we are ready to launch the InvenTree containers: ``` -docker-compose -f docker-compose.dev.yml up -d +docker-compose up -d ``` +This command launches the remaining containers: + +- `inventree-dev-server` - InvenTree web server +- `inventree-dev-worker` - Background worker + !!! success "Check Connection" Check that the server is running at [http://localhost:8000](http://localhost:8000). The server may take a few minutes to be ready. @@ -144,15 +92,23 @@ Once initial setup is complete, stopping and restarting the services is much sim To stop the InvenTree development server, simply run the following command: ``` -docker-compose -f docker-compose.dev.yml down +docker-compose down ``` ### Start InvenTree Services -To restart the InvenTree development server, simply run the following command: +To start the InvenTree development server, simply run the following command: ``` -docker-compose -f docker-compose.dev.yml up -d +docker-compose up -d +``` + +### Restart InvenTree Services + +A restart cycle is as simple as: + +``` +docker-compose restart ``` ## Editing InvenTree Source @@ -168,5 +124,5 @@ Any updates which require a database schema change must be reflected in the data To run database migrations inside the docker container, run the following command: ``` -docker-compose -f docker-compose.dev.yml run inventree-dev-server invoke update +docker-compose run inventree-dev-server invoke update ``` diff --git a/docs/start/docker_prod.md b/docs/start/docker_prod.md index 0a59b2d..9b1c407 100644 --- a/docs/start/docker_prod.md +++ b/docs/start/docker_prod.md @@ -4,21 +4,40 @@ title: Docker Production Server ## Docker Production Server -Using the [InvenTree docker image](./docker.md) streamlines the setup process for an InvenTree production server. +Using the [InvenTree docker image](./docker.md) simplifies the setup process for an InvenTree production server. -!!! warning "Static and Media Files" - The sample docker-compose configuration shown on this page uses nginx to serve static files and media files. If you change this configuration, you will need to ensure that static and media files are served correctly. When running with `debug=False`, django *will not serve these files* - see the [django documentation](https://docs.djangoproject.com/en/dev/howto/static-files/). +The following guide provides a streamlined production InvenTree installation, with minimal configuration required. -## Docker Compose +!!! info "Starting Point" + This setup guide should be considered a *starting point*. It is likely that your particular production requirements will vary from the example shown here. -It is strongly recommended that you use a [docker-compose](https://docs.docker.com/compose/) script to manage your InvenTree docker image. +### Before You Start -### Example Script +!!! warning "Docker Skills Required" + This guide assumes that you are reasonably comfortable with the basic concepts of docker and docker-compose. -An example docker compose file can be [found here](https://github.com/inventree/InvenTree/blob/master/docker/docker-compose.yml) - the documentation below will be using this docker compose file. +#### Docker Image -!!! info "Stable Version" - The example docker-compose file targets `inventree:stable` docker image by default +This production setup guide uses the official InvenTree docker image, available from dockerhub. The provided docker-compose file targets `inventree:stable` by default. + +#### Static and Media Files + +The sample docker-compose configuration outlined on this page uses nginx to serve static files and media files. If you change this configuration, you will need to ensure that static and media files are served correctly. + +!!! warning "Debug Warning" + When running with `debug=False`, django *will not serve static and media files* - refer to the [django documentation](https://docs.djangoproject.com/en/dev/howto/static-files/). + +#### Required Files + +The following files required for this setup are provided with the InvenTree source, located in the `./docker/production` directory: + +| Filename | Description | +| --- | --- | +| docker-compose.yml | The docker compose script | +| .env | Environment variables | +| nginx.prod.conf | nginx proxy configuration file | + +This tutorial assumes you are working from the `./docker/production` directory. If this is not the case, ensure that these required files are all located in your working directory. ### Containers @@ -29,133 +48,70 @@ The example docker-compose file launches the following containers: | inventree-db | PostgreSQL database | | inventree-server | Gunicorn web server | | invenrtee-worker | django-q background worker | -| inventree-proxy | nginx proxy | +| inventree-proxy | nginx proxy server | +| inventree-cache | redis cache #### PostgreSQL Database A PostgreSQL database container which requires a username:password combination (which can be changed). This uses the official [PostgreSQL image](https://hub.docker.com/_/postgres). -*__Note__: An empty database must be manually created as part of the setup (below)*. - #### Web Server -Runs an InvenTree web server instance, powered by a Gunicorn web server. In the default configuration, the web server listens on port `8000`. +Runs an InvenTree web server instance, powered by a Gunicorn web server. #### Background Worker Runs the InvenTree background worker process. This spins up a second instance of the *inventree* container, with a different entrypoint command. -#### Nginx +#### Nginx Proxy Nginx working as a reverse proxy, separating requests for static and media files, and directing everything else to Gunicorn. This container uses the official [nginx image](https://hub.docker.com/_/nginx). -!!! info "Configuration File" - An nginx configuration file must be provided to the image. Use the [example configuration file](https://github.com/inventree/InvenTree/blob/master/docker/nginx.conf) as a starting point. +#### Redis Cache - *__Note__: You must save the `nginx.conf` file in the same directory as your docker-compose.yml file* +Redis is used as cache storage for the InvenTree server. -!!! info "Proxy Pass" - If you change the name (or port) of the InvenTree web server container, you will need to also adjust the `proxy_pass` setting in the nginx.conf file! +This container uses the official [redis image](https://hub.docker.com/_/redis). ### Data Volume -InvenTree stores data which is meant to be persistent (e.g. uploaded media files, database data, etc) in a volume which is mapped to a local system directory. +InvenTree stores any persistent data (e.g. uploaded media files, database data, etc) in a [volume](https://docs.docker.com/storage/volumes/) which is mapped to a local system directory. The location of this directory must be configured in the `.env` file, specified using the `INVENTREE_EXT_VOLUME` variable. !!! info "Data Directory" Make sure you change the path to the local directory where you want persistent data to be stored. -The InvenTree docker server will manage the following directories and files within the 'data' volume: +## Production Setup Guide -| Path | Description | -| --- | --- | -| ./config.yaml | InvenTree server configuration file | -| ./secret_key.txt | Secret key file | -| ./media | Directory for storing uploaded media files | -| ./static | Directory for storing static files | +### Edit Environment Variables -## Production Setup +The first step is to edit the environment variables, located in the `.env` file. -With the docker-compose recipe above, follow the instructions below to initialize a complete production server for InvenTree. +!!! warning "External Volume" + You must define the `INVENTREE_EXT_VOLUME` variable - this must point to a directory *on your local machine* where persistent data is to be stored. -### Required Files +!!! warning "Database Credentials" + You must also define the database username (`INVENTREE_DB_USER`) and password (`INVENTREE_DB_PASSWORD`). You should ensure they are changed from the default values for added security -The following files are required on your local machine (use the examples above, or edit as required): -| File | Description | -| --- | --- | -| [docker-compose.yml](https://github.com/inventree/InvenTree/blob/master/docker/docker-compose.yml) | docker-compose script | -| [nginx.conf](https://github.com/inventree/InvenTree/blob/master/docker/nginx.conf) | nginx proxy server configuration file | -| [prod-config.env](https://github.com/inventree/InvenTree/blob/master/docker/prod-config.env) | Docker container environment variables | +### Initial Database Setup -!!! info "Command Directory" - It is assumed that all following commands will be run from the directory where `docker-compose.yml` is located. +Perform the initial database setup by running the following command: -#### Edit Configuration Files - -Edit the `docker-compose.yml` file as required. - -!!! warning "Change Data Directory" - The only **required** change is to ensure that the `/path/to/data` entry (at the end of the file) points to the correct directory on your local file system, where you want InvenTree data to be stored. - -!!! info "Database Credentials" - You may also wish to change the default postgresql username and password! - -You may also edit the `nginx.conf` and `prod-config.env` files if necessary. - -### Launch Database Container - -Before we can create the database, we need to launch the database server container: - -``` -docker-compose up -d inventree-db -``` - -This starts the database container (in this example, a PostgreSQL server). - -### Create Database - -If this is the first time you are interacting with the docker containers, the InvenTree database has not yet been created. - -!!! success "First Run Only" - If you have already created the InvenTree database you can progress to the next step - -Run the following command to open a shell session for the database: - -``` -docker-compose run inventree-server pgcli -h inventree-db -p 5432 -u pguser -``` - -!!! info "User" - If you have changed the `POSTGRES_USER` variable in the compose file, replace `pguser` with the different username. - -You will be prompted to enter the database user password (default="pgpassword", unless altered in the compose file). - -Once logged in, run the following command in the database shell: - -``` -create database inventree; -``` - -Then exit the shell with Ctrl+d - -### Database Setup - -The database has now been created, but it is empty! Perform the initial database setup by running the following command: - -``` +```bash docker-compose run inventree-server invoke update ``` This command performs the following steps: - Ensure required python packages are installed +- Create a new (empty) database - Perform the required schema updates to create the required database tables - Update translation files - Collect all required static files into a directory where they can be served by nginx -### Create Admin Account +### Create Administrator Account If you are creating the initial database, you need to create an admin (superuser) account for the database. Run the command below, and follow the prompts: @@ -163,34 +119,28 @@ If you are creating the initial database, you need to create an admin (superuser docker-compose run inventree-server invoke superuser ``` -### Configure InvenTree Options +Alternatively, admin account details can be specifed in the `.env` file, removing the need for this manual step: -By default, all required InvenTree settings are specified in the docker compose file, with the `INVENTREE_DB_` prefix. +| Variable | Description | +| --- | --- | +| INVENTREE_ADMIN_USER | Admin account username | +| INVENTREE_ADMIN_PASSWORD | Admin account password | +| INVENTREE_ADMIN_EMAIL | Admin account email address | -You are free to skip this step, if these InvenTree settings meet your requirements. +!!! warning "Scrub Account Data" + Ensure that the admin account credentials are removed from the `.env` file after the first run, for security. -If you wish to tweak the InvenTree configuration options, you can either: +### Start Docker Containers -#### Environment Variables - -Alter (or add) environment variables into the docker-compose `environment` section - -#### Configuration File - -A configuration file `config.yaml` has been created in the data volume (at the location specified on your local disk). - -Edit this file (as per the [configuration guidelines](./config.md)). - -### Run Web Server - -Now that the database has been created, migrations applied, and you have created an admin account, we are ready to launch the web server: +Now that the database has been created, migrations applied, and you have created an admin account, we are ready to launch the InvenTree containers: ``` docker-compose up -d ``` -This command launches the remaining containers: +This command launches the following containers: +- `inventree-db` - PostgreSQL database - `inventree-server` - InvenTree web server - `inventree-worker` - Background worker - `inventree-nginx` - Nginx reverse proxy diff --git a/docs/start/install.md b/docs/start/install.md index 1909f9c..7fae7e0 100644 --- a/docs/start/install.md +++ b/docs/start/install.md @@ -13,10 +13,16 @@ Install required system packages (as superuser): !!! warning "OS Specific Requirements" The following packages are required on a debian system. A different distribution may require a slightly different set of packages +!!! info "Python Version" + InvenTree requires Python version 3.8 or newer + ``` sudo apt-get update -sudo apt-get install python3 python3-dev -sudo apt-get install python3-pip python3-invoke python3-venv +sudo apt-get install \ + python3 python3-dev python3-pip python3-invoke python3-venv \ + git gcc g++ gettext gnupg \ + poppler-utils libpango-1.0-0 libpangoft2-1.0-0 \ + libjpeg-dev webp ``` !!! warning "Weasyprint" diff --git a/docs/start/intro.md b/docs/start/intro.md index d7c3dff..9c31024 100644 --- a/docs/start/intro.md +++ b/docs/start/intro.md @@ -52,7 +52,7 @@ The InvenTree documentation assumes that the operating system is a debian based InvenTree runs on [Python](https://python.org). !!! warning "Python Version" - InvenTree requrires Python 3.7 (or newer). If your system has an older version of Python installed, you will need to follow the update instructions for your OS. + InvenTree requrires Python 3.8 (or newer). If your system has an older version of Python installed, you will need to follow the update instructions for your OS. ### Invoke diff --git a/docs/stock/test.md b/docs/stock/test.md index 1de032d..5daf690 100644 --- a/docs/stock/test.md +++ b/docs/stock/test.md @@ -39,8 +39,7 @@ Multiple results can be uploaded against the same test name. In cases where mult ### Reporting -!!! missing "TODO" - Include information on the reporting plugin architecture +For any information regarding the reporting architecture, please refer to the [Report Generation](../report/report.md) page. ### Automated Test Intgration diff --git a/docs/stylesheets/bootstrap.css b/docs/stylesheets/bootstrap.css index 70b4311..8c030b7 100644 --- a/docs/stylesheets/bootstrap.css +++ b/docs/stylesheets/bootstrap.css @@ -2589,6 +2589,9 @@ html { margin-bottom: 5px; font-weight: 700; } + label:is(.md-header__button) { + display: none; + } input[type="search"] { -webkit-box-sizing: border-box; -moz-box-sizing: border-box; diff --git a/main.py b/main.py index 9f913bd..656b6c9 100644 --- a/main.py +++ b/main.py @@ -9,15 +9,17 @@ def define_env(env): # Ensure that the config template is always up to date CFG_URL = "https://raw.githubusercontent.com/inventree/InvenTree/master/InvenTree/config_template.yaml" - response = request.urlopen(CFG_URL) - print(f"Reading config template from GitHub: Response {response.status}") - - if response.status == 200: - data = response.read() + # Only perform this step if we are building on RTD server + if os.environ.get('READTHEDOCS', False): + response = request.urlopen(CFG_URL) + print(f"Reading config template from GitHub: Response {response.status}") + + if response.status == 200: + data = response.read() - if len(data) > 0: - with open("_includes/config.yaml", "w") as f: - f.write(str(data.decode())) + if len(data) > 0: + with open("_includes/config.yaml", "w") as f: + f.write(str(data.decode())) @env.macro def listimages(subdir): diff --git a/mkdocs.yml b/mkdocs.yml index e63dd91..d6bc4b3 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -13,8 +13,18 @@ theme: name: material custom_dir: _includes/overrides palette: - scheme: default - accent: light blue + - media: "(prefers-color-scheme: light)" + scheme: default + accent: light blue + toggle: + icon: material/toggle-switch + name: Switch to dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + accent: light blue + toggle: + icon: material/toggle-switch-off-outline + name: Switch to light mode logo: assets/logo.png favicon: assets/favicon.ico icon: @@ -79,12 +89,14 @@ nav: - Build Orders: build/build.md - Bill of Materials: build/bom.md - Allocating Stock: build/allocate.md - - Companies: - - Suppliers: companies/supplier.md - - Manufacturers: companies/manufacturer.md - - Customers: companies/customer.md - - Purchase Orders: companies/po.md - - Sales Orders: companies/so.md + - Buy: + - Suppliers: buy/supplier.md + - Manufacturers: buy/manufacturer.md + - Purchase Orders: buy/po.md + - Sell: + - Customers: sell/customer.md + - Sales Orders: sell/so.md + - Shipments: sell/shipment.md - Report: - Templates: report/report.md - Labels: report/labels.md @@ -93,6 +105,7 @@ nav: - Packing List: report/pack.md - Build Order: report/build.md - Order: report/order.md + - BOM: report/bom.md - Barcodes: report/barcodes.md - Context Variables: report/context_variables.md - Admin: @@ -109,20 +122,23 @@ nav: - Email: settings/email.md - Background Tasks: settings/tasks.md - Extend: - - API: extend/api.md - - Python Interface: extend/python.md - Plugins: - Overview: extend/plugins.md - - How to plugin: extend/how_to_plugin.md + - How To: extend/how_to_plugin.md - Action Mixin: extend/plugins/action.md - API Mixin: extend/plugins/api.md - App Mixin: extend/plugins/app.md - Barcode Mixin: extend/plugins/barcode.md - Event Mixin: extend/plugins/event.md + - Label Printing Mixin: extend/plugins/label.md + - Locate Mixin: extend/plugins/locate.md - Navigation Mixin: extend/plugins/navigation.md + - Panel Mixin: extend/plugins/panel.md - Schedule Mixin: extend/plugins/schedule.md - Settings Mixin: extend/plugins/settings.md - URL Mixin: extend/plugins/urls.md + - API: extend/api.md + - Python Interface: extend/python.md - Themes: extend/themes.md - Third-Party: extend/integrate.md - App: @@ -134,7 +150,6 @@ nav: - Purchase Orders: app/po.md - Settings: app/settings.md - Privacy: app/privacy.md - - Release Notes: app/release.md - Translation: app/translation.md - Suggestions: app/issues.md diff --git a/requirements.txt b/requirements.txt index 6a04e8c..13f04f5 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,25 +1,4 @@ -click>=7.1.2,<8.0 -future>=0.18.2,<1.0 -Jinja2>=2.11.2,<3.0 -joblib>=0.16.0,<1.0 -livereload>=2.6.3,<3.0 -lunr>=0.5.8,<1.0 -Markdown>=3.2.2,<4.0 -MarkupSafe>=1.1.1,<2.0 -mkdocs>=1.1.2,<2.0 -mkdocs-macros-plugin>=0.4.9,<1.0 -mkdocs-material>=7.1,<8.0 -mkdocs-material-extensions>=1.0,<2.0 -mkdocs-git-revision-date-localized-plugin==0.9.2 -mkdocs-simple-hooks==0.1.3 -nltk>=3.5,<4.0 -Pygments>=2.7.1,<3.0 -pymdown-extensions>=8.0,<9.0 -python-dateutil>=2.8.1,<3.0 -PyYAML>=5.3.1,<6.0 -regex>=2020.7.14,<2021.0 -repackage>=0.7.3,<1.0 -six>=1.15.0,<2.0 -termcolor>=1.1.0,<2.0 -tornado>=6.0.4,<7.0 -tqdm>=4.49.0,<5.0 +mkdocs-macros-plugin>=0.6,<1.0 +mkdocs-material>=8.2,<9.0 +mkdocs-git-revision-date-localized-plugin>=1.0,<2.0 +mkdocs-simple-hooks>=0.1,<1.0 \ No newline at end of file