Initial commit

doc/manual/source/components/cartodb-editor.rst

@@ -0,0 +1,27 @@
+CARTO Builder
+=============
+
+Builder is the web management component of CARTO. Within Builder you can find all the features available in CARTO. These are some of the most significant tasks you can do with Builder:
+
+  - User management. Credentials, authorization, personal info and billing.
+  - Connect datasets to your CARTO account either by importing your datasets or other ones publicly available.
+  - Create maps from your datasets
+  - Publising and permissions management of datasets and maps
+  - Synchronized tables management
+
+InternallyBuilder is the operations core of CARTO. It manages PostgreSQL metadata database, keep some metadata in sync with Redis, manages new datasets import queues with resque, etc..
+
+It is developed in Ruby on Rails and like the other components of CARTO is Open Source and you can find the source code at `CartoDB/cartodb <https://github.com/CartoDB/cartodb>`_
+
+You can find usage documentation at https://docs.carto.com/cartodb-editor.html
+
+Although you can chechout any branch of the repository most of them are usually work in progress that is not guaranteed to work. In order to run a production ready Editor service you need to use **master** branch.
+
+Service modes
+-------------
+
+The code of CARTO Builder needs to run in two different modes. HTTP server mode and background jobs mode.
+
+The **HTTP server** processes the http requests sent to the service and returns a response synchronously. Any ruby rack server can be used to start the Builder in this mode. Some examples of rack servers are mongrel, webrick, thin or unicorn.
+
+The **background jobs** mode is started with `resque <https://github.com/resque/resque>`_. In this mode the service keep polling some redis keys in order to find pending background jobs. When it finds one, it processes it and change the state of the job in redis. CARTO uses this mode for different type of jobs like datasets imports or synchronized tables.

doc/manual/source/components/cartodb-postgresql.rst

@@ -0,0 +1,15 @@
+CARTO PostgreSQL extension
+--------------------------
+CARTO's PostgreSQL extension can be found at https://github.com/CartoDB/cartodb-postgresql.
+
+This extensions is required by all the components of CARTO and it must be installed in the server where user databases are stored.
+
+It provides functions and other helpers needed by Builder, Maps and SQL APIs like:
+
+  - CartoDBfying functions which convert raw PostgreSQL tables in tables recognized by CARTO by adding some additional columns and triggers
+  - Multiuser schema handling functions
+  - Quota helpers
+  - Cache helpers
+  - etc..
+
+The CARTO extension depends on :ref:`postgis_label`.

doc/manual/source/components/maps-api.rst

@@ -0,0 +1,10 @@
+Maps API
+========
+
+The Maps API provides a node.js based API that allows you to generate maps based on data hosted in your CARTO account by applying custom SQL and CartoCSS to the data
+
+Like the other components of CARTO is Open Source and you can find the source code at `CartoDB/Windshaft-cartodb <https://github.com/CartoDB/windshaft-cartodb>`_
+
+You can find usage documentation at https://docs.carto.com/cartodb-platform/maps-api.html
+
+Although you can chechout any branch of the repository most of them are usually work in progress that is not guaranteed to work. In order to run a production ready Maps API service you need to use **master** branch.

doc/manual/source/components/postgresql.rst

@@ -0,0 +1,25 @@
+PostgreSQL
+----------
+
+`PostgreSQL <http://postgresql.org>`_ is the open source database powering CARTO.
+
+CARTO uses PostgreSQL for two purposes:
+
+* **Metadata storage**. This is the metadata used by the CARTO Builder. Builder models like users information, visualizations, or other metadata is stored in this database. The name and connection information of this database is specified on the Rails ``app_config.yml`` configuration file.
+
+* **User data storage**. Each single user or organization in CARTO has a individual PostgreSQL database. This database is created during the user signup process. Its database name and connection info is generated on the fly by the CARTO application during this process. Both values are stored within the user info in the metadata database. Every user database name contains the user UUID.
+
+Both metadata database and users databases can be hosted either in the same PostgreSQL cluster or different ones. Having both the in the same cluster is the recommended approach for small environments.
+Builder only knows how to connect to metadata database. However, within every request it checks the connection info of the user database which is stored in metadata database, as described before.
+
+At this moment CARTO requires PostgreSQL 10 version.
+
+.. _postgis_label:
+
+PostGIS
+-------
+`PostGIS <http://postgis.net>`_ is the extension which adds spatial capabilities to PostgreSQL.
+It allows working with geospatial types or running geospatial functions in PostgreSQL.
+Is is required both on the user data clusters and the metadata cluster.
+
+At this moment CARTO requires PostGIS version 2.4.

doc/manual/source/components/redis.rst

@@ -0,0 +1,21 @@
+Redis
+-----
+
+Redis is a key-value store engine used by most components of the CARTO application stack to store configuration and cache.
+
+In contrast to the PostgreSQL metadata (which is used only by the CARTO Builder), the metadata stored in Redis is shared among Builder, the SQL API, and the Maps API.
+
+.. important::
+  Even though also used as a cache, there is also persistent data stored in Redis.
+  In some environments Redis is configured by default to act without persistency
+  (see http://redis.io/topics/persistence).
+
+  You must ensure Redis is configured properly to keep its data between restarts.
+
+Data is stored in separate databases inside this Redis:
+ - Database 0: Table and visualization metadata, including map styles and named maps.
+ - Database 3: OAuth credentials metadata.
+ - Database 5: Metadata about the users, including API keys and database_hosts.
+
+
+At this moment CARTO requires Redis version 4.0 or newer with the `redis-cell` extension.

doc/manual/source/components/sql-api.rst

@@ -0,0 +1,10 @@
+SQL API
+=======
+
+The SQL API provides a node.js based API for running SQL queries against CARTO.
+
+Like the other components of CARTO is Open Source and you can find the source code at `CartoDB/CartoDB-SQL-API <http://github.com/cartodb/cartodb-sql-api>`_
+
+You can find usage documentation at https://docs.carto.com/cartodb-platform/sql-api.html.
+
+Although you can chechout any branch of the repository most of them are usually work in progress that is not guaranteed to work. In order to run a production ready SQL API service you need to use **master** branch.