.. _python_api_on_premises: .. currentmodule:: flow360 **************************** On-Premises Deployment Setup **************************** This page covers connecting the Python API to an **on-premises (Nexus) deployment** of Flow360 instead of the public cloud. If you use `flow360.simulation.cloud `_, you do not need anything on this page; follow the standard :ref:`installation and setup guide `. An on-premises deployment serves the web UI, the APIs, and object storage from a single origin. The Python API needs the individual service endpoints, and ``EnvironmentConfig.from_on_premises_url`` derives all of them from one URL — any address of the deployment, such as the web UI URL from your browser (only the scheme, host and port are used): .. code-block:: python import flow360 as fl from flow360.environment import EnvironmentConfig # Store the API key for this environment (obtain it from the deployment's # web UI under Account -> Python Authentication). fl.configure(apikey="", environment="my_on_premises") on_premises = EnvironmentConfig.from_on_premises_url( name="my_on_premises", base_url="http://nexus.example.com", # any URL of the deployment works, ) # e.g. the web UI URL from the browser on_premises.active() ``from_on_premises_url`` derives: .. list-table:: :header-rows: 1 :widths: 35 65 * - Field - Derived value * - ``web_api_endpoint`` - ``{base_url}/flow360-api`` * - ``web_url`` - ``{base_url}/flow360`` * - ``portal_web_api_endpoint`` - ``{base_url}/flow360-portal-api`` * - ``s3_endpoint_url`` - ``{base_url}/s3`` Object storage endpoint ======================= On-premises deployments advertise an object-storage endpoint that is internal to the deployment network (for example ``http://s3proxy:8080``), which client machines cannot resolve. The ``s3_endpoint_url`` setting overrides it. The default, ``{base_url}/s3``, routes uploads and downloads through the same origin as everything else and works for both Docker Compose and Kubernetes deployments. Two alternatives: .. code-block:: python # A dedicated storage port, if your deployment publishes one (deploy-specific): EnvironmentConfig.from_on_premises_url( name="my_on_premises", base_url="http://nexus.example.com", s3_endpoint_url="http://nexus.example.com:9000", ) # Trust the endpoint advertised by the server (only when the client can # resolve deployment-internal hostnames): EnvironmentConfig.from_on_premises_url( name="my_on_premises", base_url="http://nexus.example.com", s3_endpoint_url=None, ) Verify, then save ================= Run the built-in diagnostic before persisting the environment, so a broken configuration is never stored and silently reloaded in later sessions: .. code-block:: python report = fl.diagnose() if report.ok: on_premises.save_config() # persist to ~/.flow360/config.toml ``fl.diagnose()`` verifies one layer at a time — installation, endpoint configuration, proxy environment, DNS and TCP reachability, TLS certificates, HTTP, clock skew, API key, authenticated web API and portal calls, project listing, and object storage — and prints a targeted fix for every failing check. A saved environment can be re-activated in any later session with: .. code-block:: python fl.Env.load("my_on_premises").active() The Python setup above is a one-time step. Once the environment is saved, verify it from the terminal at any time: .. code-block:: bash flow360 diagnose --env my_on_premises The ``environment`` name used with ``fl.configure`` and the environment name must match: stored API keys are looked up per environment name. Both ``flow360 configure`` and ``flow360 diagnose`` also accept ``--profile `` to store and use the key under a non-default account profile. See the :ref:`CLI reference ` for all ``flow360 diagnose`` options. Before running production work ============================== .. admonition:: Important :class: warning - **Match the client version to the deployment.** Install a Python API version compatible with the Flow360 solver packaged in your deployment; mismatches surface as validation or submission failures. ``flow360 version`` prints the installed client and its solver version. - **Confirm the object storage endpoint with your administrator.** An incorrect storage endpoint prevents uploads and downloads even when project listing works, because file transfers do not use the web API. The ``storage`` diagnostic check reports which endpoint is in use and whether the one advertised by the server is reachable from your machine. - **Verify one small upload and one download** against the deployment before working with production data. File transfers can behave differently between Docker Compose and Kubernetes deployments. - **Keep the API key confidential.** It is stored locally in ``~/.flow360/config.toml``. Do not commit a setup script that contains a real key, and do not share that configuration file. Deployments behind HTTPS with a private certificate authority ============================================================== The client verifies certificates against the operating system trust store as well as its bundled public CAs, for both web API calls and file transfers. If your internal CA is already installed in the operating system trust store, no extra configuration is needed. If the internal CA is not in the operating system trust store, point the client at a PEM bundle that includes it before connecting: .. code-block:: bash export REQUESTS_CA_BUNDLE=/path/to/internal-ca-bundle.pem An explicit bundle replaces the operating system trust store for web API calls rather than adding to it, so the bundle must contain every CA the deployment's certificates chain to. To turn off the operating system trust store and verify against the bundled CAs only, set ``FLOW360_DISABLE_SYSTEM_CERTS`` before importing ``flow360``: .. code-block:: bash export FLOW360_DISABLE_SYSTEM_CERTS=1 Some deployments are served over plain HTTP precisely because a self-signed certificate is not trusted by the client machine. Match the scheme in ``base_url`` to what the deployment actually serves: use ``https`` only when the deployment presents a certificate this machine trusts, either from a public CA, through the operating system trust store, or through a bundle as above. The ``tls`` diagnostic check reports the CA bundle in use, whether the operating system trust store is consulted, and distinguishes certificate-verification failures from other connection problems.