github.com/anycable/anycable-go@v1.5.1/docs/getting_started.md (about)

     1  # Getting Started with AnyCable
     2  
     3  AnyCable is a language-agnostic real-time server focused on performance and reliability written in Go.
     4  
     5  > The quickest way to get AnyCable is to use our managed (and free) solution: [plus.anycable.io](https://plus.anycable.io)
     6  
     7  ## Installation
     8  
     9  The easiest way to install AnyCable-Go is to [download](https://github.com/anycable/anycable-go/releases) a pre-compiled binary.
    10  
    11  MacOS users could install it with [Homebrew](https://brew.sh/)
    12  
    13  ```sh
    14  brew install anycable-go
    15  ```
    16  
    17  Arch Linux users can install [anycable-go package from AUR](https://aur.archlinux.org/packages/anycable-go/).
    18  
    19  ### Via NPM
    20  
    21  For JavaScript projects, there is also an option to install AnyCable-Go via NPM:
    22  
    23  ```sh
    24  npm install --save-dev @anycable/anycable-go
    25  pnpm install --save-dev @anycable/anycable-go
    26  yarn add --dev @anycable/anycable-go
    27  
    28  # and run as follows
    29  npx anycable-go
    30  ```
    31  
    32  **NOTE:** The version of the NPM package is the same as the version of the AnyCable server binary (which is downloaded automatically on the first run).
    33  
    34  ## Usage
    35  
    36  After installation, you can run AnyCable as follows:
    37  
    38  ```sh
    39  $ anycable-go
    40  
    41  2024-03-06 13:38:07.545 INF Starting AnyCable 1.5.0-4f16b99 (with mruby 1.2.0 (2015-11-17)) (pid: 8289, open file limit: 122880, gomaxprocs: 8) nodeid=hj2mXN
    42  ...
    43  2024-03-06 13:38:56.490 INF RPC controller initialized: localhost:50051 (concurrency: 28, impl: grpc, enable_tls: false, proto_versions: v1) nodeid=FlCtwf context=rpc
    44  ```
    45  
    46  By default, AnyCable tries to connect to a gRPC server listening at `localhost:50051` (the default host for the Ruby gem).
    47  
    48  AnyCable is designed as a logic-less proxy for your real-time features relying on a backend server to authenticate connections, authorize subscriptions and process incoming messages. That's why our default configuration assumes having an RPC server to handle all this logic.
    49  
    50  You can read more about AnyCable RPC in the [corresponding documentation](./rpc.md).
    51  
    52  ### Standalone mode (pub/sub only)
    53  
    54  For pure pub/sub functionality, you can use AnyCable in a standalone mode, without any RPC servers. For that, you must configure the following features:
    55  
    56  - [JWT authentication](./jwt_identification.md) or disable authentication completely (`--noauth`). **NOTE:** You can still add minimal protection via the `--allowed_origins` option (see [configuration](./configuration.md#primary-settings)).
    57  
    58  - Enable [signed streams](./signed_streams.md) or allow public streams via the `--public_streams` option.
    59  
    60  There is also a shortcut option `--public` to enable both `--noauth` and `--public_streams` options. **Use it with caution**.
    61  
    62  You can also explicitly disable the RPC component by specifying the `--norpc` option.
    63  
    64  Thus, to run AnyCable real-time server in an insecure standalone mode, use the following command:
    65  
    66  ```sh
    67  $ anycable-go --public
    68  
    69  2024-03-06 14:00:12.549 INF Starting AnyCable 1.5.0-4f16b99 (with mruby 1.2.0 (2015-11-17)) (pid: 17817, open file limit: 122880, gomaxprocs: 8) nodeid=wAhWDB
    70  2024-03-06 14:00:12.549 WRN Server is running in the public mode nodeid=wAhWDB
    71  ...
    72  ```
    73  
    74  To secure access to AnyCable server, specify either the `--jwt_secret` or `--streams_secret` option. There is also the `--secret` shortcut:
    75  
    76  ```sh
    77  anycable-go --secret=VERY_SECRET_VALUE --norpc
    78  ```
    79  
    80  Read more about pub/sub mode in the [signed streams documentation](./signed_streams.md).
    81  
    82  ### Connecting to AnyCable
    83  
    84  AnyCable uses the [Action Cable protocol][protocol] for client-server communication. We recommend using our official [JavaScript client library][anycable-client] for all JavaScript/TypeScript runtimes:
    85  
    86  ```js
    87  import { createCable } from '@anycable/web'
    88  
    89  const cable = createCable(CABLE_URL)
    90  
    91  const subscription = cable.subscribeTo('ChatChannel', { roomId: '42' })
    92  
    93  const _ = await subscription.perform('speak', { msg: 'Hello' })
    94  
    95  subscription.on('message', msg => {
    96    if (msg.type === 'typing') {
    97      console.log(`User ${msg.name} is typing`)
    98    } else {
    99      console.log(`${msg.name}: ${msg.text}`)
   100    }
   101  })
   102  ```
   103  
   104  **Note**: The snippet above assumes having a "ChatChannel" defined in your application (which is connected to AnyCable via RPC).
   105  
   106  You can also use:
   107  
   108  - Third-party Action Cable-compatible clients.
   109  
   110  - EventSource (Server-Sent Events) connections ([more info](./sse.md)).
   111  
   112  - Custom WebSocket clients following the [Action Cable protocol][protocol].
   113  
   114  AnyCable Pro also supports:
   115  
   116  - Apollo GraphQL WebSocket clients ([more info](./apollo.md))
   117  
   118  - HTTP streaming (long-polling) ([more info](./long_polling.md))
   119  
   120  - OCPP WebSocket clients ([more info](./ocpp.md))
   121  
   122  ### Broadcasting messages
   123  
   124  Finally, to broadcast messages to connected clients via the name pub/sub streams, you can use one of the provided [broadcast adapters](./broadcasting.md).
   125  
   126  [anycable-client]: https://github.com/anycable/anycable-client
   127  [protocol]: ../misc/action_cable_protocol.md