commerce

README

Ottemo

a small, wicked fast ecommerce platform built for gophers

Install and Setup

Commerce supports golang versions 1.7+ and requires you to install the lastest stable version of dep to manage installation of dependencies. Before you run commerce for the first time, you need to create an empty database and create a user which will have permissions to create/update/insert/delete.

Download commerce to your desired GOROOT

# on my local GOROOT is found at ~/code/go
> cd ~/code/go/src/github.com

# create a directory for ottemo
> mkdir ottemo

# clone the repository
> git clone https://github.com/ottemo/commerce

Install and update dependencies for commerce

# change into the commerce directory
> cd commerce

# run dep ensure to install dependencies
> dep ensure

Build commerce with support for MySQL. There is a build script which adds in extra information, but this is not required.

# there is a build script in the bin directory
> bin/make.sh -tags mysql 

Note, you may also build commerce using the go build command, but remember to tell it which version of the database drivers to use. For instance - go build -tags mysql

The final step before running commerce for the first time is to configure a few basic settings. There exists a sample configuration file which follows the ini file format.

# copy the sample file
> cp ottemo.sample.ini ottemo.ini

Now edit the file with your favorite editor. Here is a basic version of the file for MySQL. Change the values USER and PASSWORD according to the credentials you created when first setting up the empty database.

; minimal settings for mysql driver
db.mysql.db=commerce
db.mysql.maxConnections=50
db.mysql.poolConnections=10
db.mysql.uri=USER:PASSWORD@/commerce

; let commerce know where to find/store images and videos
media.fsmedia.folder=./media/
media.resize.images.onfly=true

; if you are doing development and not using HTTPS to access commmerce set this to false 
secure_cookie=false

; to allow cross domain cookies set your desired domain (we do use cross domain cookies)
xdomain.master=http://*.local.dev/

Now you may run commerce from the commandline

> ./commerce

You should a message similiar to the following printed to stdout:

2019-04-25T15:57:45Z Connecting to MySQL DB. Timeout: 10 seconds.
Ottemo v1.4.5-jwv_basic_build_run_instructions_497-b1489 (mysql) [2019-04-25T08:57:18-07:00]
REST API Service [HTTPRouter] starting to listen on :3000
2019-04-25T15:57:45Z DB connection established.

Commerce will create a var folder which will contain logs folder and a session folder, since we didn't compile it to use redis for sessions, (which is typical for local development).

License

Mozilla Publice License 2.0

Terms and Conditions

All Submissions you make to Ottemo, Inc. (“Ottemo”) through GitHub are subject to the following terms and conditions:

1. You grant Ottemo a perpetual, worldwide, non-exclusive, no charge, royalty free, irrevocable license under your applicable copyrights and patents to reproduce, prepare derivative works of, display, publicly perform, sublicense and distribute any feedback, ideas, code, or other information (“Submission”) you submit through GitHub.
2. Your Submission is an original work of authorship and you are the owner or are legally entitled to grant the license stated above.

Copyright

© 2019 Ottemo, Inc.

Documentation

Overview

Package commerce represents the Ottemo e-commerce application entry point. This package contains the go main() function which assembles the server application.

Example:
  go build github.com/ottemo/commerce
  go build -tags mongo github.com/ottemo/commerce

Project structure and convections outline:

1. Packages structure:

	    It is well  known that GO packages represented by  directories. Within package you can have  zero or more files,
	which considered by GO as  one build unit with shared scope. There are no strict  naming convection GO lang proposes
	to file names, however there is a convection of package  naming that says you should try to name in single-word (see
	https://golang.org/doc/effective_go.html#names).

	    Despite the fact  that there is no  package files naming convection for  GO, there are couple  limits you should
	consider: file  names ends with  "_test.go" (refer to http://golang.org/pkg/testing/#pkg-overview)  and architecture
	files ends  on "*_GOOS", "*_GOARCH", "*_GOOS_GOARCH"  (i.e.  like some_amd64.go, some_windows_amd64.go,  on possible
	their values you can refer to https://golang.org/doc/install/source#environment, http://golang.org/pkg/go/build/).

	    So, these files are treated different way as well as files prefixed by "." which are considered non existent.

	    Ottemo project  trying to  follow Google recommendations,  but - with  saving clear  on code units.   So, Ottemo
	packages have multi-level folder structure with little convection on GO file naming within package.

	      file name          |  contents / meaning
	    ---------------------|-------------------------------------------------------------------------------
	    decl.go              | declarations of structures/variables/constants package wants to share
	    init.go              | package initialization routines, i.e. init() function
	                         | (refer http://golang.org/ref/spec#Package_initialization)
                             |
	    doc.go               | package description for GO doc
	                         |
	    config.go            | configuration values and their validators declaration
	    interfaces.go        | declaration of interfaces provided by package
	    manager.go           | routines for register/unregister package interface implementations
	                         |
	    helpers.go           | shortcuts for objects creation, repeatable routines, etc.
	    utils.go             | tools to work with package objects, but could be other purposes
	                         |
	    [i_interface]        | set of functions implementing particular interface (one unit case)
	    [unit].[i_interface] | set of functions implementing particular interface (multi unit case)
	                         |
	    [name]               | package specific operational logic separation (one unit case)
	    [unit].[name]        | package specific operational logic separation (multi unit case)

	    [name] and [unit] are not something specific - just some word to reflect you have different scope.

	    Considering these naming  agreements, you can determinate package  role based on just listing  package files and
	examining  of "interfaces.go"  and  "decl.go"  files.  Also  you  can consider  amount  of  interfaces this  package
	implements, by counting "i_" prefixed files.

2. Packages types/roles:

    Within  Ottemo  you  can  mostly  meet  2   types  of  packages:  interfaces  and  implementations  (models  and
actors).However it is not means that package can't play both roles - it rather exception than a rule.

    Within  "interface/model" package  you can  meet "interfaces.go",  "manager.go", "helpers.go"  files. So,  these
packages declares interfaces for future implementation packages,  but have no implementation inside. Them describing
how  model should  look  like, but  have no  references  to any  model  candidate.  These  packages mostly  contains
lightweight code.

    "Implementation/actor" package  type represented by "init.go",  "decl.go", "helpers.go", "[unit].[i_interface]",
"[unit].[other]" and other files. These packages comparatively  big, have external dependencies and most likely (but
not necessarily), implements one or couple interfaces. Actor  packages using "init.go" to make self registration and
should be closed to others packages. So, o

    The necessity of having mentioned packages types follows  from Ottemo requirement to be pluggable and extendable
as well  as GO language requirement  to not have  package cyclic dependencies. Last  one means that package  "A" can
depend  on   package  "B",   but  package   "B"  can   not  depend  on   package  "A"   then  (for   any  subpackage
respectively). Interfaces helps to  solve that issue as them contains interface declaration.  So, in previous sample
if "A"  and "B" packages have  declarations, we can move  them to package "C"  and refer both to  that package, that
package will have routines to  receive and send back objects which satisfies interface and  packages "A" and "B" can
work to each other through  this interface functions and not knowing about each other directly.  As you can see this
also allows to have replaceable packages - candidate on role.

3. Ottemo type naming convection:

    GO language have a limited set of built  in types (ref https://golang.org/ref/spec#Types"), but have a method to
declare any  amount of user  types. These  types can be  alias to base  type, struct,  function, etc. As  the naming
convention is  same far all of  them, in Ottemo  we want to be  clear on object  types we are working  with, without
making investigation on name.

    Ottemo have  the following type name  agreements, perhaps them are  little bit extending type  names and violate
naming recommendations, but it's worth it.

	  naming                 |  meaning
	-------------------------|--------------------------------------------------------
	Struct[TypeName]         | type [Name] struct { ... }
	Interface[InterfaceName] | type [Name] interface { ... }
	Func[FunctionName]       | type [Name] func { ... }
	[ObjectName]             | type [Name] struct { ... }; func (it *[Name]) { ... }

    If you have an  GO language structure object, it can be  just structure to hold values together or  be a class -
i.e.  to have methods. So,  there is slight difference between just structure and  structure with bound functions to
it - methods  (ref https://golang.org/ref/spec#Method_declarations). First one (just structure)  have fields but you
can't perform any action  on it - it just data holder,  and second one - have functions/methods you  can use to work
with. First type will be named with "Struct" prefix in Ottemo and second one - without prefix.

    Interface and function types are also very close. So  in first case you have a structure pointer with predefined
set of functions  (if structure/class do not have  all of them it is  not interface capable - interface  not fits on
it),  and in  second  case  you have  function  pointer  which also  will  not be  capable  if  will have  different
descriptors. Both  of them are  pointers to  some objects or  nil value pointer,  and both  of them have  build time
checking on interface appliance.

    We want to be clear on all types of objects you will meet in code so prefixes will help you to know this without
traveling a lot around surrounding files.

4. Variables / constants names:

    GO language mostly have one fundamental principe of identifier naming - if the first character of the identifier
name is a Unicode upper case  letter it will be exported, otherwise - not. Export -  means that you will have public
visibility,  and  other   packages  will  be  able  to   use  that  item.   This  concerns  types   as  well.   (ref
https://golang.org/ref/spec#Exported_identifiers)

    In official documentation there  are no other restricts on this except first  letter which flags export. However
in  other sources  you  can found  recommendation  to use  only  UpperCamelCase and  lowerCamelCase  naming for  all
identifiers (ref https://code.google.com/p/go-wiki/wiki/CodeReviewComments).

    Ottemo follows GO language official documentation in usage of first identifier letter and follows recommendation
on camel-case naming of variable. However for a constants (to be good visible in code) "Const" prefix used.