kore

An easy to use, scalable and secure web application framework for writing web APIs in C.
Commits | Files | Refs | README | LICENSE | git clone https://git.kore.io/kore.git

commit 46633e39781743999f0418144a049819a51c7c4a
parent 4852d5db3fb404f6406cb788d2314ac585781c96
Author: Joris Vink <joris@coders.se>
Date:   Thu, 26 Apr 2018 19:06:55 +0200

Flesh out the new kodev manual page.

Diffstat:
share/man/kodev.1 | 296++++++++++++++++++++++++++++++++++++++++++++++++++-----------------------------
1 file changed, 187 insertions(+), 109 deletions(-)

diff --git a/share/man/kodev.1 b/share/man/kodev.1 @@ -8,56 +8,41 @@ kodev \- Kore project management tool .SH DESCRIPTION This documentation describes the application management tools for building and -running a kore project. For information regarding the technical interface and +running a Kore project. For information regarding the technical interface and C bindings, look to -.BR KORE(3) +.BR kore(3) where these functions and structures are described. -.BR kore +.BR Kore projects may be managed using the following OPTIONS; .BR create .RS Create a new application skeleton with the name that is passed to it. This will -create a new directory with all the files required to begin hacking about. -This will also generate a self-signed certificate \fIunless\fR single\-binary -is enabled in the -.BR conf/build.conf -and \fBNOTLS=1\fR is set in the active flavour. Note that this certificate -should not be used for production. +create a new directory with all the files required to begin hacking. See the +\fBGENERATED FILES\fR section for more information. .RE .BR build .RS -Build the application. The properties of this build are read from -.BR conf/build.conf -and the semantics of which are discussed in \fBCONFIGURATION FILES\fR. +Build the application. See the \fBBUILDING\fR section for more information. .RE .BR run .RS -Run an application (\-fnr implied). The current directory is the path of the -project to be run. This will read from the \fBconf/app.conf\fR discussed in -\fBCONFIGURATION FILES\fR unless otherwise specified. This will build the -application\(emif necessary\(emand start it in the foregound. \fB^C\fR -will stop the process. By default, \fBkore\fR binds to port 8888 on -.BR localhost -and again, this behaviour may be configured in your -.BR conf/app.conf . -If the single\-binary mode is turned on, then that binary will be run as -opposed to the default -.BR $PREFIX/bin/kore . +Start the application in the foreground. See the \fBRUNNING\fR section for +more information. .RE .BR reload .RS -Reload the application (SIGHUP sent). This in turn triggers a reload of all the -currently loaded modules. +Reload the application. This is a shortcut to sending SIGHUP to the parent +process (see kore_pid). .RE .BR info .RS -Show info on kore on this system. Namely; active flavour, output type, kore -features, kore source and kore binary. +Show information about the application configuration. Namely; active flavor, +output type, Kore features, Kore source and Kore binary. .RE .BR clean @@ -65,9 +50,9 @@ features, kore source and kore binary. Cleanup the build files. .RE -.BR flavour +.BR flavor .RS -Switch between build flavours with the argument being the new flavour. +Switch between build flavors with the argument being the new flavor. .RE .BR help @@ -78,123 +63,216 @@ Show the help synopsis. .BR \-p .RS Option used in conjunction with \fBcreate\fR to generate an application for use -with +with the .BR pyko +Kore framework. .RE -.SH CONFIGURATION FILES -When one calls a \fBbuild\fR on the application, it will read the -.BR conf/build.conf. -This defines attributes of the build such as whether you wish to produce a -single binary instead of a dynamic library. If you choose to do so, also -ensure to set -.BR kore_source -and -.BR kore_flavour -and update the \fBldflags\fR to include the appropriate libraries you intend -to link the binary with. You may also set custom \fBcflags\fR either global to -the flavours or per flavour configurations. +.SH GENERATED FILES +Executing the +.BR create +command will generate several new files under the directory matching the +application name specified. + +These files are: -When a \fBcreate [app]\fR is called, kodev will also create an \fBapp.conf\fR -where 'app' is the name of the project. This configuration describes to Kore -what modules to load, how validators work, what page handlers to map and which -functions and more. The specifics of which are discussed below; .RS +.BR conf/build.conf +.RS +The build configuration. +.RE -.BR socket_backlog -Maximum length to queue pending connections. See \fBlisten(\fR2\fB)\fR +.BR conf/app.conf +.RS +The Kore application configuration. +.RE -.BR bind -Bind to a given IP address and port number. +.BR src/app.c +.RS +The initial placeholder source code. +.RE -.BR chroot -The path to which the worker processes will \fBchroot()\fR into. +.BR cert/server.pem +.RS +The self-signed auto-generated x509 certificate. +.RE -.BR runas -The username the worker process inherit privileges from. +.BR cert/key.pem +.RS +The key matching the self-signed x509 certificate. +.RE -.BR workers -The number of worker processes to spawn and keep alive. Default is 1. +.BR dh2048.pem +.RS +The 2048-bit DH parameters used by TLS. +.RE +.RE -.BR worker_max_connections -The number of active connections each worker will accept. Default is 250. +If you specify the +.BR -p +flag the generated files will be for use with +.BR pyko +instead. -.BR worker_rlimit_nofiles -Limit of maximum open files per worker. +Those files are: -.BR worker_accept_threshold -Limit the number of new connections a worker can accept in a single event loop. -Per default, \fBkore\fR will accept as many new connections it can until the -\fBworker_max_connections\fR. Default is 'disabled'. +.RS +.BR kore.conf +.RS +The Kore application configuration. +.RE +.RE -.BR worker_set_affinity -Workers bind themselves to a single CPU by default. To disable this behaviour, -set this option to 0. +.RS +.BR handlers.py +.RS +The initial placeholder python page handler. +.RE +.RE -.BR pidfile -Store the pid of the parent process in the file passed to this. Default is -none. +.RS +.BR __init__.py +.RS +The python initialization code. Sets up the kore listener, etc. +.RE +.RE -.BR http_header_max -Maximum size of HTTP headers (argument in bytes). Default is 4096. +.RS +.BR cert/server.pem +.RS +The self-signed auto-generated x509 certificate. +.RE +.RE -.BR http_body_max -Maximum size of an HTTP body (argument in bytes). Default is 1024000. -Note that if it is set to 0, this disallows requests with a body all together. +.RS +.BR cert/key.pem +.RS +The key matching the self-signed x509 certificate. +.RE +.RE + +.RS +.BR dh2048.pem +.RS +The 2048-bit DH parameters used by TLS. +.RE +.RE -.BR http_body_disk_offload -Number of bytes after which \fBkore\fR will use a temporary file to hold the -HTTP body, instead of holding it in memory. If this is set to 0, no disk -offloading will be done. This is turned off by default; 'disabled'. -.BR http_body_disk_path -Path where \fBkore\fR will store any temporary HTTP body files. The default -is \fItmp_files\fR. +.SH BUILDING +Executing the +.BR build +command will build your application. How this happens is instructed by +the +.BR conf/build.conf +configuration file. This file supports the following directives: + +.RS +.BR single_binary +[yes|no] +.RS +If set to \fByes\fR the build system will produce a single binary containing +both your application code and the Kore code allowing you to distribute +your application more easily. -.BR http_keepalive_time -Maximum number of seconds and HTTP connection may be kept open by a browser. -The default is 20 seconds, set to 0 to turn off keep-alive entirely. +If set to \fBno\fR the build system will produce a standard dynamicly +linked library that will be loaded into Kore at runtime. +.RE +.RE -.BR http_hsts_enable -If not 0, this is the age of the HSTS header that is included in all responses. -The default is 31536000 seconds. +.RS +.BR kore_source +[path] +.RS +Must be set to point to the a Kore source code directory. Used only if +.BR single_binary +option is set to \fByes\fR. -.BR http_request_limit -The number of HTTP requests \fBkore\fR workers will process in one loop. -The default is 'disabled'. +.BR Example: +kore_source=/home/joris/src/kore +.RE +.RE +.RE -.BR websocket_timeout -The number of seconds a websocket connection is kept open without traffic. -The default here is 120 seconds. +.RS +.BR kore_flavor +[build options] +.RS +Defines the build arguments for building Kore. Used only if +.BR single_binary +option is set to \fByes\fR. -.BR task_threads -The number of OS threads to use for background tasks. The default here is -\(emvery conservatively\(em2. +.BR Example: +kore_flavor=NOTLS=1 +.RE +.RE -.BR tls_version -The TLS versions allowed, by default this is set to \fIonly\fR TLSv1.2. +.RS +.BR cflags +.RS +Standard +.BR CFLAGS +used when compiling the application source code. +.RE +.RE -.BR tls_cipher -The server TLS ciphersuites that are permitted. The default is a very -sane set of ciphersuites preferring AEAD ciphers and ephemeral key exchanges -over static RSA. +.RS +.BR ldflags +.RS +Standard +.BR LDFLAGS +used when linking the application source code. +.RE +.RE -.BR tls_dhparam -The DH parameters to load (\fBrequired\fR). The default is dh2048.pem +Note that the +.BR build +command obeys the environment variables +.BR CC +and +.BR CXX +.SH RUNNING +Executing the +.BR run +command will start your application in the foreground. + +What binary it executes depends +on whether or not the +.BR single_binary +flag was set in build configuration. If the +.BR single_binary +flag was enabled the +.BR run +command will execute the binary produced by the build system. If the +.BR single_binary +flag was not enabled the +.BR run +command will execute the +.BR $PREFIX/bin/kore +binary. +In both cases the +.BR run +command will pass the \fB\-fnr\fR command line options to the binary. .RE .SH EXAMPLES -Changing flavour of the build; +Changing flavor of the build; .RS -kodev flavor osx +$ kodev flavor osx .RE Creating a new application 'app' with \fBpyko\fR support; .RS -kodev create \-p app +$ kodev create \-p app +.RE + +Building your application; + +.RS +$ kodev build .RE .SH REPORTING BUGS, CONTRIBUTING && MORE @@ -205,7 +283,7 @@ More information can be found at .BR <https://kore.io/> .SH AUTHOR -.BR kore +.BR Kore developed by Joris Vink .BR <joris@coders.se>