Item Hut Documentation¶
Contents:
Item Hut Intro¶
What is Item Hut?¶
Item Hut is free and open source channel’s manager, ERP, CRM, inventory, and marketing analysis system, mainly focusing on B2B and online portals, written in Python3 and PostgreSQL 9.5+.
Versioning and release schedule¶
Item Hut is a rolling release, however, we do not currently supply update scripts. For the Python code, this will not matter much, however, the database often goes through structural changes, and migration scripts are currently not included in the SQL files.
Item Hut keeps up with the latest stable releases of each needed project and we do not consider backwards compatibility to prior versions of PostgreSQL, Python, or any other needed library. When later versions of PostgreSQL are released, Item Hut will require that version of the database to run without errors.
Goals of the project, for the end-user¶
Item Hut is presently not a single-click install system. This may change in the future.
We have attempted to make installation as simple as possible, however, you will have to have some technical know-how.
Systems and Programs¶
Item Hut is built on the most recent version of Fedora Linux. It has not been tested on any other version of Linux, nor has it been tested on Mac OS or Windows.
Further details of the installation are included in the install section.
System Design Goals¶
Item Hut is, first and foremost, an engine, which should be able to be used on any backend system or even a headless command line, on a local machine or a server. For this reason, we ignore some web-building best practices.
Permissions and Licensing¶
While I am unable to enforce this, I am a strong believer that a customer’s data is their data. I ask that, if you use this program, you allow your customers to own all the data they have supplied to you either through their own input or through the APIs.
While I do not require this, I am interested in spreading the word about this program. If you wish to use this program, please offer attribution.
Released under the Mozilla Public License Version 2.0.
Installation¶
System Requirements¶
note: Item Hut has not been built or tested on Mac OS or Windows.
(install with your package manager)
- PostgreSQL 9.5
- PostgreSQL 9.5 Server
- PostgreSQL 9.5 Devel
- gcc
- python3-devel
- redhat-rpm-config (if on redhad / fedora / CentOS)
- Python3
- Python3 Devel
running pip3 install will download the following packages (see setup.py):
- Python3 Bottle 0.12.9
- Psycopg2 2.6.2
- Beaker 1.8.0
- bcrypt 3.1.0
- py-bcrypt 0.4
- google-api-python-client
The Database¶
Initial Setup¶
create the itemhut database:
$ su - postgres
$ createdb itemhut
If this is your first time using PostgreSQL, you have to create a password for the postgres user:
$ psql
postgres=# alter user postgres with encrypted password "<password>"
postgres=# \q
edit the pg_hba.conf (still as postgres):
$ cd data
$ [editor] pg_hba.conf
change peer to md5 then restart the PostgreSQL server. Create a .pgpass File:
cd to the home directory of the user who is running the system:
$ cd
create .pgpass:
$ touch .pgpass
edit .pgpass with your prefered editor:
$ [editor] .pgpass
add the following, filling in the bracketed:
<host>:<port>:itemhut:postgres:<password>
in general, the .pgpass file will look like this, where password is whatever you made the password when you updated the postgres user password:
localhost:5432:itemhut:postgres:<password>
Install Item Hut¶
clone the repo:
$ git clone https://github.com/dt1/itemhut.git
cd to directory:
$ cd itemhut
run setup:
$ pip3 install . --upgrade
setup the database:
$ python3 build_db.py
Run Itemhut:
$ python3 inventory.py
open localhost:8082 in your browser.
You will see a “Create First User” page.
Create Users¶
Creating the Super Admin¶
The Super Admin is automatically created when you start Item Hut and create the initial user. You will be redirected to the main system, logged in.
Creating Other Users¶
Go to admin>Add User.
You will be allowed to add a username, password, real name, role, and type.
Roles¶
Roles focus the user on a particular area and match the headings in the top menu. For example, a user assigned the “customers” role will only be allowed to see the customers sub section.
note: User roles are still under development. In the future, we plan to add groups, warehouse views, and more refined read-only permissions.
At this point, the Admin role has all of the same permissions as the Original Admin. We suggest you create a regular admin for working with Item Hut here on out.
Types¶
User Types allow Item Hut to focus on keeping data integrity. For right now, we only have the “sales” role. In order for a user to do a sale, he or she must be a member of the “sales” role. This would prevent say, a picker, from creating a sale, and so forth.
note: User Types are still under development. Just as user roles, we plan to add groups, which will allow a user to, for example, pick orders and create sales. For now, all new users have the sales type.
Internals¶
When Item Hut starts up, the system checks for a “super admin” role in the database. If this role does not exist, the system will redirect to /initialize and have you create a new super admin.
If you forget the password for the super admin, you can delete the super admin from the databse, while keeping all of your data intact. This is why we suggest not using the super admin for anything in Item Hut. Password retrieval is not available in Item Hut at this time.
Warehouse Administration¶
To create a new warehouse, go to admin>Add Warehouse.
There are two kinds of warehouses in Item Hut, B&M, which is a warehouse where you control all aspects of inventory, and 3PL, which is a 3rd party warehouse.
B&M¶
A B&M warehouse allows you to create, add, and delete pallet and picking locations. You will also be allowed to create, add, delete, and move pallets.
You will also be allowed to do outbound QC. Inbound QC will be added later. The logging mechanisms do not function properly at this time.
3PL¶
A 3PL warehouse will only allow you to add products and view running inventory.
Internals¶
Internally, B&M and 3PL warehouses behave the same. Instead of adding user-defined pallet locations, the pallet locations are added by system-generated hashes. If you switch a 3PL werehouse to a B&M warehouse, all the same features of a B&M warehouse will be available, though it will take some manual work to get all the data to reflect the reality of the B&M warehouse.
The opposite is also true: you are able to convert a B&M to 3PL and the system will behave as a 3PL. Although here is not GUI option to do this at the moment, you are able to change this setting at the database level.
Warehouse Management¶
Adding Pallet and Picking Locations¶
To manage warehouse picking and pallet locations, go to Admin>Manage Warehouses then select the warehouse you would like to add locations to. The warehouse must me a B&M to add picking and pallet locations.
There are two ways to add picking and pallet locations:
1- You can add each location manually.
2- You can bulk load locations
The bulk load requires a .csv file. Each location in Column A will recieve it’s own cell. Do not add headers to the file.
If there are duplicates in the file, or duplicates of locations in the database, the duplicates will be ignored while the new locations will be added.
Example of a valid .csv file:
Images¶
Item Hut takes a data management approach to handling product images. There are multiple ways to upload and manage images, but every image that is inserted into Item Hut is placed in the image gallery.
Product Level Images¶
When creating or editing products and kits (found under Products), you are able to upload an image directly to the product or you can grab and image from the product gallery.
The image will be automatically inserted into the image gallery, which you will be able to find under Tools > Image Gallery.
Image Gallery¶
The Image Gallery will show, and hold, all images you have uploaded.
The Image Gallery allows you to delete and replace images. An image that is deleted from the image gallery will no longer show up at the product image level, and any image that is replaced will show up at the product level. To prevent confusion, the gallery shows all the skus the image is tied to.
There are no optical programs built into Item Hut, therefore, you are able to upload the same image multiple times, and, if you choose, refine the images to each individual product. This allows you to either treat each individual image as global to all similar SKUs, or, create images that are isolated to each SKU.
Product Level and Image Gallery Binding¶
As an example, suppose we have 2 skus, shirt-aa and shirt-bb. We have two options: load the image into the product page, or, load the image into the gallery and then grab this image during product creation or editing.
If you would like shirt-aa and shirt-bb to have the same image but you’d like to have the flexibility to refine each image at a later date, without affecting the other sku, you can:
1- Add the image to each product. This will create a binding in the Image Gallery. You will have two images that look the same, but bound to two different SKUs.
2- Add the image to the Gallery (Tools > Bulk Load Images) then bind the images to the products via the “Use Image Gallery” button.
This process may take a little bit getting used to, but this perspective of using cross references is the pattern of everything in Item Hut.
Bulk Loading Images¶
The image bulk-loader can be found under Tools > Bulk Load Images. You can either add one image, or many images.